Rating
A star rating that is operable from the keyboard and answers in half steps when asked.
@luc/uiExamples
A fractional, read-only rating
`readOnly` turns it into a display: no interaction, and the value is announced as one string rather than as five controls.
<Rating value={4.5} readOnly allowHalf size="sm" label="Average rating" />Star counts
`max` is the number of stars, not a scale to convert: ten stars is a score out of ten.
<Rating value={7} max={10} readOnly label="Score out of ten" />Three sizes
`sm` sits in a table cell, `md` is the default, and `lg` is a rating the reader is being asked for.
<Rating value={3} size="lg" allowHalf label="Size lg" />Interactive, and clearable
Arrow keys step by half a star, and choosing the current value again clears it while `clearable` is true.
<Rating defaultValue={3.5} allowHalf clearable label="Your rating" />Usage
import { Rating } from "@luc/ui";<Rating value={4.5} allowHalf readOnly label="Average rating" />Package setup — peer requirements, the stylesheet and the provider — is on installation.
API
Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.
| Export | Kind | Signature |
|---|---|---|
Rating | 9 documented props | ({ className, value, defaultValue, onValueChange, max, allowHalf, readOnly, size, label, clearable, ...props }: RatingProps) => import("@types/react").JSX.Element |
Rating props
Type: RatingProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
allowHalf? | boolean | undefined | — | Allow half steps (click the left half of a star). |
clearable? | boolean | undefined | — | Clears the value when the current one is chosen again. Default `true`. |
defaultValue? | number | undefined | — | Uncontrolled start value. Default 0. |
label? | string | undefined | — | Accessible name. Required unless the rating sits in a labelled field. |
max? | number | undefined | — | Number of stars. Default 5. |
onValueChange? | ((value: number) => void) | undefined | — | |
readOnly? | boolean | undefined | — | Display only — no interaction, announced as a value. |
size? | "sm" | "md" | "lg" | undefined | — | |
value? | number | undefined | — | Controlled value. |
Guidelines
Do
- Use `readOnly` for a rating you are showing; the component announces one value instead of five controls.
- Set `max` for anything other than five stars: it is the number of stars, not a scale to convert.
- Pass `label` unless the rating sits in a labelled `Field`, which names it for you.
Don't
- Use stars for a precise score with no visible number: pair it with the value as text.
- Let a reader clear a rating that the form requires — leave `clearable` off when an answer is mandatory.
- Use a rating where a slider would do: it is a five- or ten-point judgement, not a continuous quantity.
Accessibility
The group is a radio group in effect: it keeps one tab stop, the arrow keys step by a star — or half a star with `allowHalf` — and `readOnly` turns the whole thing into a single announced value rather than a set of controls.
Family
Forms
Inputs, their validation surfaces and the form lifecycle around them.
24 documented entries in this family. Open the family index
Related