Rating
newEveryone's a critic. Now they have stars.
Hosts see the stars, not your name.
Open Props in the corner of the example to try color, size, orientation and disabled. size runs from xs to xl on the control tokens, so a rating lines up with a Button or Input of the same size: each star's box is the control height, 28px to 48px, the star two thirds of it, and the space between stars half the control gap.
color fills the stars in Button's colours or your own, primary by default. For gold stars, use warning: the fill is the bright tone and the edge its text shade, which keeps the star's outline at 3:1 against the page where amber alone doesn't. Empty stars keep the --input outline in every colour.
Installation
Usage
<script setup lang="ts">
import { Field, FieldLabel } from '@/components/ui/field'
import { Rating, RatingItem } from '@/components/ui/rating'
const stars = ref(0)
</script>
<template>
<Field>
<FieldLabel>Rate your stay</FieldLabel>
<Rating v-slot="{ items }" v-model="stars">
<RatingItem v-for="item in items" :key="item" :item="item" />
</Rating>
</Field>
</template>
v-model is a number, 0 while nothing is picked. A rating never writes it on its own, so an untouched form stays untouched.
Rating holds the value and gives items, the star numbers; each RatingItem draws one star. To show a score instead of asking for one, use RatingDisplay with RatingDisplayItem (see Readonly).
Under the stars is a radio group: one radio per step, each named "3 out of 5", and a single tab stop. Put it in a Field, or give it an aria-label.
Examples
Half steps
step splits each star: 0.5 for halves, 0.25 for quarters, 0.1 for tenths. Click the start of a star for its first half, the end for the whole star. hoverable previews the value under a mouse; a finger never previews, because a tap would leave the preview behind.
Readonly
For showing a score, not asking for one, RatingDisplay takes a value and draws it exactly, 4.3 fills the fifth star to 30% whatever the step, and screen readers hear one picture, "Rated 4.3 out of 5", instead of five dimmed radios. In a field it reads the label first.
It has no radios and no listeners, so use it for review lists and product grids.
- Mira
Quiet, warm, and the coffee is excellent.
- Tomás
Lovely room. The lift was out for two days.
Clearable
With clearable, picking the current value again clears it to 0. On a keyboard, that's Space on the checked star.
Click the current star, or press Space on it, to clear.
Hover label
hover fires with the value under the pointer, and 0 once it leaves, so you can put a word next to the stars. Give labels.item the same words, and screen readers hear them too.
Icons
Put an icon in RatingItem to replace the star. It renders once for the empty layer and once per step for the filled one; the slot's filled tells them apart, so v-slot="{ filled }" can draw a different empty icon. An svg in the filled layer is filled with the colour. RatingDisplayItem takes an icon the same way.
Stars are clipped from the start for half steps, so pick a symmetric icon.
States
A disabled rating turns grey, filled and empty alike, and leaves the tab order. A disabled Field or FieldSet disables it too. An invalid one turns destructive, outlines included, whatever its color.
Form
With Formisch, bind field.input and let the schema say a rating is required: v.minValue(0.5) rejects both an untouched and a cleared rating.
Review your order
Ceramic pour-over set, delivered on Tuesday.
In a plain <form>, give it a name. Nothing picked submits an empty value, so native required stops the form until a star is picked.
<template>
<form action="/reviews" method="post">
<Rating v-slot="{ items }" name="rating" required aria-label="Rating">
<RatingItem v-for="item in items" :key="item" :item="item" />
</Rating>
<Button type="submit">Send</Button>
</form>
</template>
Right to left
In a right-to-left layout, the stars fill from the right, the first half of a star is its right half, and Left and Right swap. Set dir, or wrap the app in Reka's ConfigProvider.
Vertical
orientation="vertical" stacks the stars from top to bottom. The arrow keys become Up and Down.
Touch target
Each star is as wide as the space it takes in the row: 21px at xs, 28px at md, and a half step is half of that. touch-target grows each star to 48px across the row, expand when it stands alone, wrapper when it sits close to others. It can't grow them along the row, where the stars already touch, so neighbours never overlap and half steps still split in the middle. Where fingers matter, also pick sm or larger, which keeps whole stars at least 24px wide, the minimum WCAG asks for.
Known limits
- Reka's Rating is in alpha. Its keyboard table lists Up and Down for a horizontal rating, but they only work when vertical; the table below is what it does.
- With
stepbelow 1, every step is a radio with its own window listeners:0.1means 50 radios and about 200 listeners per rating. Show lists withRatingDisplay. - A value off the step, like 3.7 with
step0.5, shows as 3.5 and checks no radio. Round it, or show it withRatingDisplay. - On reka-ui before 2.11, a server-rendered rating with
stepbelow 1 logs a hydration warning (reka-ui#2964). It looks right anyway, because every colour is opaque; 2.11 drops the warning. - Filled steps carry Reka's
data-state="active", which reka-ui v3 renames. Style through the item's icon andcolorrather thandata-state. - Clicking the field label doesn't focus the rating, as with Slider. The label still names it.
API Reference
class is also accepted and merged over the base classes.
Rating
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | numberThe starting value when |
| disabled | — | booleanDisables the rating. Also set by a disabled field. |
| orientation | "horizontal" | DataOrientation
|
| dir | — | DirectionReading direction. In |
| name | — | stringSubmits the value with its form under this name. Nothing picked submits an empty value. |
| required | — | booleanMarks the rating required, and fails native validation while nothing is picked. Also set by a required field. |
| length | 5 | numberHow many stars. |
| clearable | — | booleanPicking the current value again, by click or Space, clears it to |
| hoverable | — | booleanPreviews the value under a mouse or a pen. A touch never previews. |
| step | 1 | 1 | 0.5 | 0.25 | 0.1How finely a star splits. |
| id | — | stringOverrides the |
| size | "md" | RatingSizeMatches a Button of the same size. Each star's box is the control height, 28px for |
| color | "primary" | RatingColor | (string & {})Colour role of the filled stars. |
| touchTarget | "none" | RatingTouchTargetGrows each star's pressable area to at least 48px across the row without changing how it looks. |
| labels | — | Partial<RatingLabels>Screen reader names, |
| modelValue | — | numberThe value, bound with |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: number | undefined]Fires when a star is picked or the value is cleared. |
| hover | [value: number]Fires with the value under the pointer while |
| Slot | Scope and description |
|---|---|
| default | { items: number[]; }The items, one |
RatingItem
| Prop | Default | Type and description |
|---|---|---|
| item* | — | numberThe star's number, from 1 to the rating's |
| Slot | Scope and description |
|---|---|
| default | { filled: boolean; }The icon, a star by default. Rendered for the empty layer with |
RatingDisplay
| Prop | Default | Type and description |
|---|---|---|
| value | 0 | numberThe value to show. Fractions are drawn exactly, so 4.3 fills the fifth star to 30%. |
| length | 5 | numberHow many stars. |
| orientation | "horizontal" | "horizontal" | "vertical"
|
| dir | — | "ltr" | "rtl"Reading direction. In |
| size | "md" | RatingSizeMatches a Button of the same size, as on |
| color | "primary" | RatingColor | (string & {})Colour role of the filled stars, as on |
| labels | — | Partial<RatingLabels>Screen reader name, |
| id | — | stringOverrides the |
| name | — | stringSubmits the value with its form under this name, in a hidden input. |
| disabled | — | booleanGreys the stars. Also set by a disabled field. |
| Slot | Scope and description |
|---|---|
| default | { items: number[]; }The items, one |
RatingDisplayItem
| Prop | Default | Type and description |
|---|---|---|
| item* | — | numberThe star's number, from 1 to the display's |
| Slot | Scope and description |
|---|---|
| default | { filled: boolean; }The icon, a star by default, rendered for the empty layer with |
Props
- defaultValue
numberThe starting value whenv-modelis not used.- disabled
booleanDisables the rating. Also set by a disabled field.- orientation
"horizontal" DataOrientationverticalstacks the stars from top to bottom, and the arrow keys become Up and Down.- dir
DirectionReading direction. Inrtlthe stars fill from the right, and Left and Right swap.- name
stringSubmits the value with its form under this name. Nothing picked submits an empty value.- required
booleanMarks the rating required, and fails native validation while nothing is picked. Also set by a required field.- length
5 numberHow many stars.- clearable
booleanPicking the current value again, by click or Space, clears it to0.- hoverable
booleanPreviews the value under a mouse or a pen. A touch never previews.- step
1 1 | 0.5 | 0.25 | 0.1How finely a star splits.0.5picks halves, by the start or end of a star;0.1gives each star ten radios, so show long lists withRatingDisplay.- id
stringOverrides theidtaken from a surrounding field.- size
"md" RatingSizeMatches a Button of the same size. Each star's box is the control height, 28px forxsto 48px forxl, and the star two thirds of it.- color
"primary" RatingColor | (string & {})Colour role of the filled stars.warninggives gold stars. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. Empty stars keep the--inputoutline; an invalid rating turnsdestructivewhatever its colour.- touchTarget
"none" RatingTouchTargetGrows each star's pressable area to at least 48px across the row without changing how it looks.wrapperalso reserves that space in layout;expandmay overlap neighbours above and below.- labels
Partial<RatingLabels>Screen reader names,{ item(value, length) }, for other words or another language. English by default, "3 out of 5" for a step.- modelValue
numberThe value, bound withv-model.0means nothing is picked.
Emits
- update:modelValue
[value: number | undefined]Fires when a star is picked or the value is cleared.- hover
[value: number]Fires with the value under the pointer whilehoverable, and0once it leaves.
Slots
- default
{ items: number[]; }The items, oneRatingItemper star. Receivesitems, the star numbers from 1 tolength.
Props
- item*
numberThe star's number, from 1 to the rating'slength.
Slots
- default
{ filled: boolean; }The icon, a star by default. Rendered for the empty layer withfilledfalse and for the filled layer withfilledtrue; ansvgin the filled layer is filled with the colour.
Props
- value
0 numberThe value to show. Fractions are drawn exactly, so 4.3 fills the fifth star to 30%.- length
5 numberHow many stars.- orientation
"horizontal" "horizontal" | "vertical"verticalstacks the stars from top to bottom.- dir
"ltr" | "rtl"Reading direction. Inrtlthe stars fill from the right.- size
"md" RatingSizeMatches a Button of the same size, as onRating.- color
"primary" RatingColor | (string & {})Colour role of the filled stars, as onRating.warninggives gold stars.- labels
Partial<RatingLabels>Screen reader name,{ readonly(value, length) }, for other words or another language. "Rated 4.3 out of 5" by default; anaria-labelgoes in front of it.- id
stringOverrides theidtaken from a surrounding field.- name
stringSubmits the value with its form under this name, in a hidden input.- disabled
booleanGreys the stars. Also set by a disabled field.
Slots
- default
{ items: number[]; }The items, oneRatingDisplayItemper star. Receivesitems, the star numbers from 1 tolength.
Props
- item*
numberThe star's number, from 1 to the display'slength.
Slots
- default
{ filled: boolean; }The icon, a star by default, rendered for the empty layer withfilledfalse and the filled layer withfilledtrue.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| rating | data-size, data-color, data-orientation, data-touch-target, data-disabled | The root, role="radiogroup". data-size and data-color are set even when left at their defaults. |
| rating-display | data-size, data-color, data-orientation, data-disabled | RatingDisplay's root, one role="img" named after its value. |
| rating-item | data-hovered, data-disabled | One star's box. Draws the hover circle, and holds its own stacking context so the steps' z-index stays inside. |
| rating-empty-icon | — | The empty star behind the steps. Draws the focus ring. |
| rating-indicator | aria-checked, data-disabled | One step, a role="radio" button over the start of the star. aria-checked is on the picked step only. |
| rating-icon | — | The filled star inside a step, clipped to the step's share of the box; in a display, clipped to the value. |
Accessibility
| Key | Action |
|---|---|
| Tab | Moves focus to the checked step, or the first one when nothing is picked, without picking it. |
| ArrowRight / ArrowLeft | Moves one step and picks it, stopping at the ends. Only when horizontal; in rtl the two swap. |
| ArrowDown / ArrowUp | Moves one step and picks it. Only when vertical. |
| Home / End | Moves focus to the first or last step without picking it. |
| PageUp / PageDown | Same as Home and End. |
| Space | Picks the focused step. On the checked step with clearable, clears the rating. |
| Enter | Does nothing, so it never submits the form by accident. |
The rating is a radio group, a pattern screen readers already know, and each step is a radio named after its value. Invalid, required and the field's description and error go on the group, not on each star; the stars themselves are hidden from screen readers.
From nothing picked, Right Arrow picks the second star, as in any radio group. Press Space for the first.