Rating

Installation

pnpm dlx shadcn@latest add @wisty/rating

The CLI installs the Radix or Base UI file to match your project.

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

When to use

Use it

People give a score out of a few points by picking an icon, like a star rating for a support case, an article or a survey question.
The score reads best as stars, hearts or thumbs up filling from the left, with words like Bad and Good under the two ends.
A feedback form or a customer satisfaction (CSAT) question in a survey.

Don't use it

To show a score someone already gave, like an average rating. Use Gauge with variant="rating".
For a 0 to 10 scale or a row of numbers, like Net Promoter Score. Use Linear scale.
For a few named answers, like Yes, No and Not sure. Use Radio group.
For a value along a long range, like a percentage. Use Slider.

Usage

import { Rating, RatingLabel, RatingLabels } from "@/components/wisty/rating"

Rating
└── RatingLabels
    ├── RatingLabel
    └── RatingLabel

<Rating name="article" aria-label="Rate this article">
  <RatingLabels>
    <RatingLabel>Bad</RatingLabel>
    <RatingLabel>Good</RatingLabel>
  </RatingLabels>
</Rating>

Rating draws max icons, five by default, and the score is the string "1" to max. The first RatingLabel sits under the first icon and the last under the last icon. Leave out RatingLabels for a rating with no words under it.

Choosing the same icon again keeps the score. To clear it, control value and set it to null, as the Clearing a score example does. For an error, set aria-invalid on Rating, which marks the group, and point aria-describedby at the FieldError. With required, the radios are also invalid to the browser until a score is chosen.

Examples

Clearing a score

A controlled `value` and a Clear button that sets it to `null`, since choosing the same icon again keeps the score.

API reference

Part	Built on	Description
`Rating`	`<div>` (opens in a new tab)	A score from 1 to max, picked from a row of icons that fill up to the chosen one.
`RatingLabels`	`<div>` (opens in a new tab)
`RatingLabel`	`<span>` (opens in a new tab)

`Rating`

A score from 1 to max, picked from a row of icons that fill up to the chosen one.

Prop	Type	Default	Description
`value`	`string \| null`		The chosen score, "1" to `max`, controlled. `null` for none.
`defaultValue`	`string`		The score chosen at first, when uncontrolled.
`onValueChange`	`(value: string) => void`		Called with the chosen score when someone picks an icon.
`max`	`number`	`5`	How many icons, and the highest score. A whole number of 1 or more.
`icon`	`LucideIcon`	`StarIcon`	The icon to repeat, from lucide-react.
`name`	`string`		The inputs' name, to submit the score with a form. Generated when not given.
`disabled`	`boolean`	`false`	Disables every icon.
`required`	`boolean`	`false`	A score must be chosen before the form submits.
`form`	`string`		The id of a form the inputs belong to, outside it.

SLDS mapping

Rating is a div with role="radiogroup", the group SLDS leaves to the fieldset around it. Each icon is a visually hidden native radio (slds-assistive-text) and a label holding the icon, as a Salesforce survey's rating question draws it. RatingLabels and RatingLabel are the words a survey shows under the ends.

Known gaps:

SLDS 2 has no rating component, so the colors come from its hooks: the accent fill of a chosen icon, the icon color at rest and the disabled color.
Icons are lucide's, stroked outlines that fill when chosen, where a survey draws Salesforce's own icons.
No smiley icon set: a face's eyes and mouth disappear when it fills. Use stars, hearts or thumbs up.

Prop	Value	SLDS	Notes
`icon`	`StarIcon` (added)	`none (a survey's star rating)`	The default: stars. Any lucide icon whose outline fills, like HeartIcon or ThumbsUpIcon.
`(a chosen score)`	`checked` (added)	`none`	The icons up to the chosen one fill with the accent color. Hovering changes nothing, and the icon being pressed fills.
`disabled`	`true` (added)	`input type="radio" disabled`	Every icon turns gray, and a chosen score stays filled.

Keyboard interactions

Key	Action
Tab	Moves focus to the chosen icon, or the first icon with no score.
Arrow Right or Arrow Down	Chooses the next icon.
Arrow Left or Arrow Up	Chooses the previous icon.
Space	Chooses the focused icon when none is chosen.

Accessibility

Name the group with aria-labelledby pointing at a FieldLegend, or with aria-label.
Each icon is named "3 of 5", in English. The icons themselves are hidden from screen readers.
RatingLabels describes the group, after any aria-describedby you pass, so a screen reader hears what the ends mean.

Motion

Choosing a score fades the icons up to it in, and the ones after it out, over 300ms. Reduced motion keeps the fade, since only the color changes.
Hovering an icon doesn't fill anything. Pressing one fills it while the pointer is down.

Rules

Keep the icons in one Rating: the group holds the score, the name and the keyboard.
Use an icon whose outline fills to a solid shape, like StarIcon, HeartIcon or ThumbsUpIcon. An icon with lines inside a closed outline, like a face, fills to a plain disc.
Put at most two RatingLabels in RatingLabels, one for each end.