All components (204)

Rating

Choice · Rating · .amset-rating

What it is and when to use it

Stars to rate or to show an average. When it can be touched it is a radio group, with a name in words for each star ("3 stars"); in read-only mode it is an image with its text ("Average rating: 4.3 of 5") and supports half stars.

When to use it

Asking for an opinion: the rating of an order or a product.
Showing the average with readOnly, showValue and count: "4.3 (128)". An average halfway between is drawn as a half star and the exact figure goes beside it; rounding="exact" draws the real percentage.
shape="compact" (read-only) puts the rating and a few small stars in a pill, for lists and cards.
size: stars of 16, 22 (default) or 28 px; the label, the rating, the help and the error grow with them. outline draws all of them in gold and the filled ones also with a line.
icon and unit change the symbol and what each option is called ("1 level", "3 levels").

When not to

The breakdown of opinions by stars, with bars: RatingSummary.
A survey from 0 to 10: NpsSurvey.
A number that is typed: NumberField.

Keyboard: to rate, each star is a native radio of the same group: a single Tab to enter and leave, and the arrows move and choose at once. With allowsRemove, Delete or Backspace leave it empty and notify onChange with null; pressing the chosen star again with the mouse or a finger does too. It works the same controlled (value, which accepts null for "not rated") as uncontrolled (initialValue). In read-only mode it is not a control and does not receive focus.

Accessibility: to rate it is a radiogroup named like the label, and each star says its number in words; the help and the error (hint and error, the field pieces) are read as the group's description, and with an error the outline of the empty ones turns red. In read-only mode it is an image (role="img") with the label, the rating and the maximum in its name. The filled star uses the --amset-gold token, measured at 3:1 against the backgrounds. Each pressable star is at least 24 px with a mouse and 44 px with a finger, with no gaps that step on its neighbor. The focus is a 2 px ring around the star. hiddenLabel removes the label from view, not from the reader.

Motion: with the mouse over it, the rating that would result is seen before pressing, and what would be lost shows in a muted gold; the pointed star grows a little and the pressed one gives way. The stars fill with a fade and the one that is marked enters with a short jump.

Context: it goes inside LocaleProvider (or AmsetProvider), which decides how the rating is written: 4,3.

Fine-tuning: CSS variables --amset-rating-size (the side of each star: 16, 22 or 28 px depending on size), --amset-rating-slot (the spacing between stars), --amset-rating-padding (the air around each pressable star), --amset-rating-color (the filled one, --amset-gold), --amset-rating-empty (the outline of the empty one), --amset-rating-stroke (its thickness), --amset-rating-stroke-filled (0 or 1: whether the filled one also carries a line), --amset-rating-radius (the corners of the focus) and --amset-rating-font (the rating and the count) and --amset-rating-pill (the background of the compact one).

What it looks like

<Rating label="Service rating" value={nota} onChange={setNota} max={5} />
<Rating label="Average of customers (read-only)" initialValue={4} readOnly count={128} />

Props

Import it with import { Rating } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	What is being rated. Required: "4 of 5" on its own says nothing.
`allowsRemove`	`boolean`	Pressing the chosen star again (or Delete) leaves the rating empty.
`className`	`string`	Merged with the library classes; it does not replace them.
`count`	`number`	How many ratings are behind it: "4.3 (128)".
`disabled`	`boolean`	—
`error`	`string`	—
`hiddenLabel`	`boolean`	The label for the screen reader only (the pill already explains itself).
`hint`	`string`	—
`icon`	`ReactNode`	Another symbol: a heart, a flame. It also changes `unit`.
`initialValue`	`number \| null`	The rating at the start, without controlling it from outside.
`max`	`number`	How many stars there are. 5 by default.
`onChange`	`(value: number \| null) => void`	Reports the chosen rating, or `null` when it is removed (with `allowsRemove`).
`outline`	`boolean`	Full stars also with an outline: thinner, less heavy.
`readOnly`	`boolean`	Shows the average without letting it be touched. Accepts decimals.
`rounding`	`RatingRounding`	How a half in between is drawn. `exact` draws the real percentage.
`shape`	`RatingShape`	`compact` puts the rating and some small stars into a pill, for lists and cards where five large icons eat up the row. Read-only.
`showMax`	`boolean`	With the rating, the maximum too: "4.0 of 5".
`showValue`	`boolean`	The rating beside the stars.
`size`	`"sm" \| "md" \| "lg"`	The side of each star: 16, 22 (default) or 28 px.
`unit`	`RatingUnit`	What each unit is called, for the name of each option.
`value`	`number \| null`	The score, controlled from outside (with `onChange`). `null` is "not rated": that way it is emptied without becoming `undefined`, which would release it from the control. In read-only mode it accepts decimals.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-rating-size`	`1.375rem`
`--amset-rating-slot`	`0.25rem`
`--amset-rating-padding`	`0.1875rem`
`--amset-rating-color`	`var(--amset-gold)`
`--amset-rating-empty`	`var(--amset-border-bold)`
`--amset-rating-stroke`	`1.5`
`--amset-rating-stroke-filled`	`0`
`--amset-rating-radius`	`var(--amset-radius-sm)`
`--amset-rating-font`	`var(--amset-text-sm)`
`--amset-rating-pill`	`var(--amset-gold-soft)`

How to change it

.amset-rating {
  --amset-rating-size: ...;
  --amset-rating-slot: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: