Rating | NDS - Vanilla National Design System

Display Rating

Read-only stars that show an existing score. Use span elements for non-interactive display.

Interactive Rating

Clickable stars that let users submit their own rating. Use button elements to enable interaction automatically.

Dropmenu Rating

A compact rating trigger that expands into an interactive voting panel. Used in hero sections and content headers to collect feedback without leaving the page.


<div class="nds-dropmenu">
    <button class="nds-btn nds-subtle nds-menu-btn nds-dropmenu-trigger nds-md" type="button">
        <div class="nds-rating nds-xs" data-rating="4.5">
            <span class="nds-rating-star" aria-hidden="true"></span>
            <span class="nds-rating-star" aria-hidden="true"></span>
            <span class="nds-rating-star" aria-hidden="true"></span>
            <span class="nds-rating-star" aria-hidden="true"></span>
            <span class="nds-rating-star" aria-hidden="true"></span>
        </div>
        <span class="nds-label"><span class="nds-total-rate">4.5</span> - (<span class="nds-total-votes">18</span>) Votes</span>
    </button>
    <div class="nds-dropmenu-menu nds-rating-dropmenu" hidden="">
        <div class="nds-dropmenu-item" data-no-auto-close>
            <span class="nds-label">Rate this service</span>
            <div class="nds-rating" data-rating="0">
                <button class="nds-rating-star" type="button" aria-label="1 star"></button>
                <button class="nds-rating-star" type="button" aria-label="2 stars"></button>
                <button class="nds-rating-star" type="button" aria-label="3 stars"></button>
                <button class="nds-rating-star" type="button" aria-label="4 stars"></button>
                <button class="nds-rating-star" type="button" aria-label="5 stars"></button>
            </div>
        </div>
        <div class="nds-dropmenu-footer">
            <hr class="nds-divider nds-lg">
            <div class="nds-dropmenu-action nds-grid">
                <button class="nds-btn nds-primary nds-dropmenu-item" data-no-auto-close>
                    <span class="nds-label">Vote</span>
                </button>
            </div>
        </div>
    </div>
</div>

Built-in Features

Auto-initialization

Activates when .nds-rating is on the page. Components added dynamically are detected and initialized automatically.

Automatic Mode Detection

Stars built with <button> elements become interactive with hover preview and click selection. Stars built with <span> elements render as display-only.

Half-Star Precision

Decimal ratings display half stars automatically. Values with a decimal of 0.3 or higher show a half star; below 0.3 rounds down to the nearest whole.

Keyboard Navigation

Full arrow key traversal (RTL-aware), Enter and Space to select, Home and End to jump, and Escape to blur focus.

Responsive Sizing

Large stars scale down from 48px to 40px on mobile viewports, keeping proportions balanced on smaller screens.

Programmatic Control

Get, set, disable, and enable ratings through the instance API. Listen for ratingChange events to react to user selections.

Usage Guidelines

Best Practices

Use display ratings to show aggregate scores, average reviews, or any read-only quality indicator alongside products, services, or content
Use interactive ratings inside feedback forms, review submissions, and satisfaction surveys where users provide their own score
Place interactive ratings inside a Dropmenu when collecting feedback from a compact trigger, such as a "Rate this" button. The component includes a nds-rating-dropmenu layout for this pattern
Do not use a rating component for binary choices (like/dislike). Use a Switch or toggle button instead
Do not use ratings to represent progress or completion. Use a Progress component instead
Choose the brand variant for government and official contexts where the default golden color does not align with the visual identity
Pick extra small or small sizes for inline display next to titles or list items, medium for standard layouts, and large for featured reviews or hero placements
Keep star counts consistent across your application. Five stars is the standard and matches user expectations
Set data-rating to the initial value for display ratings. For interactive ratings collecting a fresh score, set it to 0
Always include aria-label on each star button with the numeric value (e.g., "3 stars") so screen readers announce the rating position

Modifier Classes

Class	Description
`nds-xs`	Extra small stars (16px)
`nds-sm`	Small stars (24px)
`nds-md`	Medium stars (32px, default)
`nds-lg`	Large stars (48px, scales to 40px on mobile)
`nds-brand`	Switches star colors from golden yellow to the brand green palette
`nds-rating-dropmenu`	Layout class for placing a rating inside a dropmenu with proper spacing. Apply on `.nds-dropmenu-menu` so the styles match in both DOM positions (the menu is portaled to `<body>` while open).

Data Attributes

Attribute	Description
`data-rating="3.5"`	Set on `.nds-rating` to define the initial score. Accepts whole numbers and decimals (0 to 5).

CSS Custom Properties

Property	Default	Description
`--star-size`	32px	Width and height of each star
`--star-color`	--rating-star-normal-default	Color of unselected (empty) stars
`--star-selected`	--rating-star-selected-default	Color of filled stars
`--star-pressed`	--rating-star-pressed-default	Color applied on active/press state
`--star-hovered`	--rating-star-hovered-default	Color applied on hover (brand variant only)

JavaScript API

The NDS.Rating API initializes rating components and exposes instance methods on element.ndsRating. For dynamically added ratings, call NDS.Rating.init() or rely on automatic MutationObserver detection.


// ── Instance methods (element.ndsRating) ────────────
const el = document.querySelector('.nds-rating');

// Get the current rating value
el.ndsRating.getRating();              // Returns number (e.g. 3.5)

// Set a new rating value (0 to star count)
el.ndsRating.setValue(4);              // Updates visuals and fires ratingChange event

// Disable the rating (prevents clicks and keyboard)
el.ndsRating.setDisabled(true);

// Enable a disabled rating
el.ndsRating.setDisabled(false);
el.ndsRating.enable();                 // Shorthand for setDisabled(false)

// Check if the rating is currently disabled
el.ndsRating.isDisabled();             // Returns boolean

// ── Events ──────────────────────────────────────────
// Fires on the .nds-rating element when the value changes
// Bubbles, so you can listen on a parent container
document.addEventListener('ratingChange', (e) => {
    e.detail.rating;    // New rating value (number)
    e.detail.element;   // The .nds-rating element
});

// ── Namespace methods (NDS.Rating) ──────────────────
NDS.Rating.init();                     // Initialize all .nds-rating elements on the page
NDS.Rating.reinit();                   // Re-initialize (same as init)
NDS.Rating.enableRating(element);      // Initialize and enable a specific rating element