A star rating that works with the keyboard and in forms, and shows an average.
$ pnpm dlx shadcn@latest add @dashral/ratingInstallation
$ pnpm dlx shadcn@latest add @dashral/ratingAdds the component, the components it builds on, its npm packages and the theme tokens it uses. Or by its full URL: https://dashral.com/r/rating.json
Usage
import { Rating } from "@/components/dashral/rating"
<Rating label="Your rating" name="rating" onValueChange={(stars) => setStars(stars)} />Using the npm package? Import from @dashral/ui/components/rating instead, here and in the examples; the rest is the same.
Examples
API reference
Rating
| Prop | Type | Default |
|---|---|---|
label | ReactNodeShown above, linked to the control. | — |
description | ReactNodeA hint under the control. | — |
error | boolean | ReactNodetrue shows the error style; a message also shows under the control. | — |
labelAction | ReactNodeAt the end of the label's row, e.g. a “Forgot password?” link or the current value. | — |
withAsterisk | booleanMarks the label with an asterisk, e.g. alongside required. | false |
value / defaultValue | numberThe rating, controlled or initial; 0 for none. With readOnly, a fraction too (4.6). | 0 |
onValueChange | (value: number) => voidCalled with the new value. | — |
max | numberHow many icons. | 5 |
readOnly | booleanShows the value without taking input, a fraction filling part of an icon. | false |
clearable | booleanPicking the current rating again clears it. | true |
labels | string[]A word for each value, lowest first: each icon's name for screen readers. | — |
showLabel | booleanWith labels: the hovered or picked value's word beside the icons. | false |
icon | ReactElementAnother icon, e.g. a heart; it's filled in the color. | a star |
color | "primary" | "neutral" | "info" | "success" | "warning" | "destructive" | "highlight"The filled icons. | "warning" |
size | "sm" | "default" | "lg"The icons' size. | "default" |
name | stringThe form field's name; sends the number, nothing at 0. | — |
disabled / required | booleanAs on other controls. | — |
classNames | { root, label, description, error, item, valueLabel }Classes for each part; valueLabel is showLabel's word. | — |
className | stringExtra classes, merged with cn() so yours win. | — |
Keyboard
| Keys | Action |
|---|---|
| Tab | To the rating (the picked star, or the first) |
| ←or→or↑or↓ | Pick the next or previous value (in reading order) |
| Space | Pick the focused value; on the picked one, clear it |
Accessibility
- With label, description or error, the id, aria-describedby and aria-invalid are wired up for you.
- A radio group: each icon is a radio named "3 stars" (or its label), so it's read as "3 stars, 3 of 5".
- readOnly is one image named "4.6 out of 5".
- Its words come from the kit's messages, so a LocaleProvider translates them.