Rating
A row of stars for rating something from 1 to a maximum.
Usage
import { Rating, RatingCaption, RatingStars } from '@epilot/spark-ui/rating'<Rating labels={['Very poor', 'Poor', 'Okay', 'Good', 'Excellent']}>
<RatingStars aria-label="Rate your installer" />
<RatingCaption>Choose a rating</RatingCaption>
</Rating>Rating holds the value and settings; RatingStars draws the stars and
RatingCaption the line below them. The caption shows the label of the hovered
star, else of the chosen one, else its own children, so pass a placeholder as
children. Leave the caption out when there are no labels to show.
The value is 1-based: the first star is 1. Concorde's onChange counted from
0, so add one when you migrate. Concorde's name (the accessible name)
becomes aria-label or aria-labelledby on RatingStars; Spark's name is the
form field name.
Examples
Sizes
small (16px stars), medium (24px, default) and large (32px). Above five
stars, each size draws smaller stars so the row stays compact.
More stars
Controlled
Choosing the current star again does not clear it. To clear a rating, set
value to null.
Value: none ·
Read-only
Disabled
In a Field
A FieldLabel cannot name a group of stars through htmlFor. Give it an id
and pass that id to RatingStars as aria-labelledby. In a read-only Field
the stars take the Field's label without it.
API Reference
Rating
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | null | — | The chosen star, 1-based. null means no rating. |
defaultValue | number | null | null | The starting value when uncontrolled. |
onValueChange | (value: number) => void | — | Called with the chosen star, 1-based. |
max | number | 5 | How many stars to draw. |
labels | string[] | — | One label per star: its accessible name and its caption text. |
size | 'small' | 'medium' | 'large' | 'medium' | Star size. |
readOnly | boolean | false | Shows the value without letting it change. |
disabled | boolean | false | Dims the stars and blocks changes. |
name | string | — | Submits the value with a form under this name. |
Renders a div stacking the stars and caption. Forwards all div HTML attributes plus className. Under <Field readOnly>, Rating still needs its own readOnly.
RatingStars
Wraps Base UI Radio Group and renders a div. Forwards all div HTML attributes plus className, such as aria-label and aria-labelledby.
RatingCaption
Renders a p; its children are the placeholder. Forwards all paragraph HTML attributes plus className.
Accessibility
RatingStarsrendersrole="radiogroup"with onerole="radio"per star. Name the group witharia-labeloraria-labelledby.- Each star is named by its entry in
labels, or by its number without labels. - Keyboard:
Tabmoves focus into and out of the stars, the arrow keys move between and choose stars. RatingCaptionis hidden from screen readers, because the stars already announce the same labels.- Inside a
Field, the stars are described by itsFieldDescriptionandFieldErrorand marked invalid while the Field has an error.