Rating
Accessible React star rating that works as an input or a read-only display, with half-star precision, sizes, brand tone, and full keyboard support.
Rating collects or displays a star score. Use readOnly for display, allowHalf for half stars, and tone="brand" for SA green.
When to use
Use Rating to collect satisfaction after a service is delivered, or to display an average score. Set readOnly for display and allowHalf when averages need finer precision. Keep the scale at five stars; users know it.
For a question with labelled options, such as "How easy was this?", a RadioGroup gives clearer answers.
Examples
Props
Props declared by Rating. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "md" | "lg" | ||
value | number | Controlled value (0…max). .5 increments are allowed when allowHalf. | |
defaultValue | number | Uncontrolled initial value. Defaults to 0. | |
onValueChange | (value: number) => void | Fires with the chosen rating. | |
max | number | Number of stars. Defaults to 5. | |
allowHalf | boolean | Allow half-star (.5) precision. | |
readOnly | boolean | Display only - no interaction, exposed as role="img". | |
disabled | boolean | Non-interactive and dimmed. | |
label | react.ReactNode | Visible field label. | |
helperText | react.ReactNode | Hint shown below the field. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the field when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
tone | "default" | "brand" | SDGA Style axis. default (gold) · brand (SA green). Recolor per
instance via the --ddga-rating-color CSS variable. | |
icon | react.ReactNode | Symbol rendered instead of the default star (e.g. a heart). Used for both
the empty and filled layers - fill/empty colors come from CSS, so pass an
icon that uses currentColor. Defaults to the SDGA star. | |
formatValueText | (value: number, max: number) => string | Builds the accessible value text / read-only label. Defaults to
"{value} out of {max} stars". Override for localization. | |
id | string | ||
className | string | ||
aria-label | string | Defines a string value that labels the current element. | |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
Accessibility
The interactive Rating is a slider role: arrow keys change the score, Home and End jump to the extremes, and aria-valuetext announces the value with its label. A read-only Rating renders as an image with an accessible name, so it is announced but not focusable.
Label the control through label or aria-label, and use the error message to explain a missing rating.