Rating

Use a rating to collect a score, like how a stay went, or to show one, like an average. Each star is a radio, so it works like a radio group, with one value and a single tab stop.

"use client"

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating aria-label="Rating" defaultValue={3}>
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Installation

npm install @ui-sdk/react @ui-sdk/core

Composition

Use the following composition to build a Rating:

Rating
└── RatingItem

Rating renders its children once per star, so put one RatingItem inside it. Without children, it renders a RatingItem with no icon.

Usage

Import the parts and put them together:

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating aria-label="Rating" defaultValue={3}>
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Name the rating with aria-label, or put it in a Field whose label names it. Without defaultValue, nothing starts checked and Tab enters on the first star.

Stars

Put your icon in RatingItem. Each item says how much of its star the shown score covers: --rating-fill goes from 0 to 1, data-filled marks a whole star and data-partial the star a score ends partway through. The radios that pick the score sit over the icon, so it needs no events of its own.

[data-slot="rating-item"] {
  color: lightgray;
}

[data-slot="rating-item"][data-filled] {
  color: gold;
}

For half stars and averages, paint the icon up to calc(var(--rating-fill) * 100%), like with a gradient behind a star-shaped mask.

Pass a function as the item's children to render from its state, like an icon that fills once the score covers the star:

<RatingItem>
  {({ fill }) => (
    <StarIcon aria-hidden="true" fill={fill === 1 ? "currentColor" : "none"} />
  )}
</RatingItem>

Half Stars

Set step={0.5} to split each star in two. Each half is its own radio, named like "2.5 stars", and a press on the first half of a star picks the half score.

"use client"

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating aria-label="Rating" step={0.5} defaultValue={3.5}>
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Preview

While a pointer moves over the stars, they show the score under it: --rating-fill follows the pointer, and data-highlighted marks the stars up to it. Leaving the stars shows the score again. Touch has no preview, since a tap picks the score at once.

Deselectable

Set deselectable to let people clear their score: a press on the checked star, or Space on it, sets the score back to null.

"use client"

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating aria-label="Rating" defaultValue={4} deselectable>
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Read-Only

Set readOnly to show a score that can't change, like an average. Any score shows, like 4.2, which fills a fifth of the last star. The rating becomes one image for screen readers, and its radios are hidden from them.

Name a read-only rating with getValueLabel, so its name includes the score. An aria-label would replace it.

"use client"

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating
      value={4.2}
      readOnly
      getValueLabel={(value, max) => `Rated ${value} out of ${max}`}
    >
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Disabled

Set disabled to stop every star from being focused or changed. A disabled rating submits nothing.

"use client"

import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"

function Example() {
  return (
    <Rating aria-label="Rating" defaultValue={2} disabled>
      <RatingItem>
        <StarIcon aria-hidden="true" />
      </RatingItem>
    </Rating>
  )
}

export { Example }

Controlled

Pass value and update it in onValueChange. Call details.cancel() in the callback to keep the current score. A controller from createRatingController() sets the score from anywhere, like the Clear Rating button below. Create one controller per mounted rating.

"use client"

import {
  createRatingController,
  Rating,
  RatingItem,
} from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"
import * as React from "react"
import { useLog } from "./log"

function Example() {
  const log = useLog()
  const [rating] = React.useState(() => createRatingController())
  const [value, setValue] = React.useState<number | null>(4)

  return (
    <div>
      <div data-slot="controls">
        <button type="button" onClick={() => rating.setValue(null)}>
          Clear Rating
        </button>
      </div>
      <Rating
        aria-label="Rating"
        value={value}
        onValueChange={(next, details) => {
          setValue(next)
          log(`value: ${next} (${details.reason})`)
        }}
        controller={rating}
      >
        <RatingItem>
          <StarIcon aria-hidden="true" />
        </RatingItem>
      </Rating>
    </div>
  )
}

export { Example }

See State and Events for controlled state, cancellation and debugging.

Form

Each radio renders a hidden native radio, so the rating takes part in forms. Set name to submit the score; nothing submits without a name or a score. required blocks submission until there's a score, and a reset returns to defaultValue.

"use client"

import { Field, FieldLabel } from "@ui-sdk/react/field"
import { Rating, RatingItem } from "@ui-sdk/react/rating"
import { StarIcon } from "lucide-react"
import { useLog } from "./log"

function Example() {
  const log = useLog()

  return (
    <form
      data-slot="stack"
      onSubmit={(event) => {
        event.preventDefault()
        log(`Submitted stay=${new FormData(event.currentTarget).get("stay")}`)
      }}
    >
      <Field>
        <FieldLabel>Rate your stay</FieldLabel>
        <Rating name="stay" required>
          <RatingItem>
            <StarIcon aria-hidden="true" />
          </RatingItem>
        </Rating>
      </Field>
      <div data-slot="row">
        <button type="submit" data-variant="solid">
          Send Review
        </button>
        <button type="reset">Reset</button>
      </div>
    </form>
  )
}

export { Example }

Stars and Labels

Set max for the number of stars, and loop to let the arrow keys wrap from the last star to the first. Each radio is named by getValueLabel, which gets the score and max and says "1 star" or "3 stars" by default.

<Rating
  aria-label="Difficulty"
  max={10}
  loop
  getValueLabel={(value, max) => `${value} of ${max}`}
>
  <RatingItem />
</Rating>

Styling

Parts are unstyled. Use data-filled, data-partial, data-checked and data-highlighted on each star, and --rating-fill for how full it is. data-disabled, data-readonly and data-required are on the rating and its stars.

Each part has a data-slot, such as rating-item, and its state attributes are listed under Data Attributes.

RatingItem

Data Attributes

Rating

[data-slot="rating"]

RatingItem

[data-slot="rating-item"]

API Reference

Props and callbacks are the same as below, as React props.

Rating

State

What render functions, state-based class names and slots receive.

Reasons

details.reason says why the score changed.

Controller

Create one with createRatingController() and pass it as controller.

Every write method takes an optional { reason, event }, runs the change callback like a press, and returns false when the change is canceled.

Events

Callbacks get the new score first, then the details.

Accessibility

A rating is a radio group, so it follows the WAI-ARIA radio group pattern and behaves like native radios that share a name. Each star holds a button with the radio role per score it can pick, and a hidden native radio that takes part in forms. Icons inside the stars should be hidden from screen readers with aria-hidden, since each radio is already named. A read-only rating has the img role instead, named by getValueLabel.

Keyboard

Tested Behavior

Every line below is an automated test.