Rating

new

Everyone's a critic. Now they have stars.

Demo
3 / 5

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.

Half steps
3.5
2.75

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.

Readonly
4.3
1,284 reviews
5 stars
62%
4 stars
23%
3 stars
8%
2 stars
3%
1 star
4%
  • 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.

Clearable
4 / 5

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.

Hover label
Pick a rating

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.

Icons

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.

States
Rate the service to continue.

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.

Form

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.

Direction
3.5

Vertical

orientation="vertical" stacks the stars from top to bottom. The arrow keys become Up and Down.

Vertical
Difficulty 2 of 4

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.

Touch target
none
expand
wrapper

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 step below 1, every step is a radio with its own window listeners: 0.1 means 50 radios and about 200 listeners per rating. Show lists with RatingDisplay.
  • A value off the step, like 3.7 with step 0.5, shows as 3.5 and checks no radio. Round it, or show it with RatingDisplay.
  • On reka-ui before 2.11, a server-rendered rating with step below 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 and color rather than data-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.

Data attributes

data-slotAttributesDescription
ratingdata-size, data-color, data-orientation, data-touch-target, data-disabledThe root, role="radiogroup". data-size and data-color are set even when left at their defaults.
rating-displaydata-size, data-color, data-orientation, data-disabledRatingDisplay's root, one role="img" named after its value.
rating-itemdata-hovered, data-disabledOne 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-indicatoraria-checked, data-disabledOne 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

KeyAction
TabMoves focus to the checked step, or the first one when nothing is picked, without picking it.
ArrowRight / ArrowLeftMoves one step and picks it, stopping at the ends. Only when horizontal; in rtl the two swap.
ArrowDown / ArrowUpMoves one step and picks it. Only when vertical.
Home / EndMoves focus to the first or last step without picking it.
PageUp / PageDownSame as Home and End.
SpacePicks the focused step. On the checked step with clearable, clears the rating.
EnterDoes 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.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.22.0

    ac0cc05 — Checkbox, Radio, Switch and Slider no longer declare as and asChild, as Rating already does: Reka's slot cloned the control's own indicator, thumb or track into the root, which left an inert control. The props are gone from their API tables too.

    89ede95 — ColorPicker snaps back to its model when the parent turns an update down, as Rating does, instead of showing a colour the model never took.

    750df71 — A Field or FieldSet inside a disabled FieldSet is disabled too, so a Slider, Rating or ColorPicker in its own Field stops taking focus and input while the form is locked. Only disabled passes down; invalid and required stay with the part that sets them.

    70d1620 — Colours written inside arbitrary values and variables now resolve where the element sits, so a .dark island (or any subtree that sets a token) gets its own: the filled Input, InputGroup and DatePicker underline, the Table hover, selected and stripe tints, the disabled Slider and Rating fills and the ColorPicker checkerboard read --theme(--color-x) instead of var(--color-x), which Tailwind resolves once on :root. The ripple wave reads --state-pressed where it is pressed (the ripple item no longer pins --kappa-ripple-opacity on :root), so a subtree that changes --state-pressed changes the wave as well as the state layer.

  4. core 0.16.0

    70d1620 — Colours written inside arbitrary values and variables now resolve where the element sits, so a .dark island (or any subtree that sets a token) gets its own: the filled Input, InputGroup and DatePicker underline, the Table hover, selected and stripe tints, the disabled Slider and Rating fills and the ColorPicker checkerboard read --theme(--color-x) instead of var(--color-x), which Tailwind resolves once on :root. The ripple wave reads --state-pressed where it is pressed (the ripple item no longer pins --kappa-ripple-opacity on :root), so a subtree that changes --state-pressed changes the wave as well as the state layer.

  5. registry 0.14.0

    90d509d — Rating is built from parts: Rating holds the value and gives items, and each RatingItem draws one star, so <Rating v-model="stars" v-slot="{ items }"><RatingItem v-for="item in items" :key="item" :item="item" /></Rating>. A custom icon goes inside RatingItem, with filled telling the empty layer from the filled one; the icon and empty-icon slots are gone. Showing a score is its own part pair, RatingDisplay with RatingDisplayItem, which takes a value and draws it exactly as one role="img" picture; the readonly prop is gone.

  6. registry 0.13.0

    11239a6 — New Rating component, on Reka UI's Rating: a row of stars to pick a score in whole, half, quarter or tenth steps. It takes size from xs to xl on the control tokens, so it lines up with a Button of the same size, and color like the other choice controls, with warning for gold stars. hoverable previews the value under a mouse or a pen but never under a finger, clearable takes the score back, and touch-target, vertical and right-to-left layouts and icon and empty-icon slots work as elsewhere.

    readonly shows an exact value, 4.3 fills the fifth star to 30%, as one picture named "Rated 4.3 out of 5", with no radios for screen readers to announce. In a Field it takes the field's id, label, description, error, invalid, required and disabled state. In a plain form, a rating with nothing picked, or cleared, submits an empty value, so native required holds until a star is picked.