Rating

import { Rating } from "@/components/ui/rating";

export default function RatingDemo() {
  return (
    <Rating
      label="How was your delivery?"
      description="Your rating is shared with the courier."
      defaultValue={4}
    />
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/rating

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Rating } from "@/components/ui/rating";

tsx

<Rating label="How was your delivery?" defaultValue={4} />

<Rating isReadOnly value={4.5} />

value is a number from 0 (no rating) to maxValue. onChange receives a number.

When to use

Rating: a quick, low-effort score, such as product reviews, satisfaction after a support chat, or rating an article.
Radio Group: when each value needs a written label the user should read before choosing.
Slider: a value on a continuous or fine-grained scale.
Meter with segments: a level, not something the user rates.

Anatomy

tsx

<Rating>                    {/* role="radiogroup" */}
  {/* Label */}
  {/* icons: one radio per value */}
  {/* value text / value label (optional) */}
  {/* Description, FieldError */}
</Rating>

<Rating isReadOnly />        {/* role="img" with "4.5 out of 5" */}

Part	Renders	Notes
`Rating`	`<div role="radiogroup">`	React Aria `RadioGroup`, horizontal. Handles arrow keys, `name` for forms, `isRequired` and validation.
Item	`<label>` with a hidden radio	One per value. Its accessible name is `"3 of 5"`, or the matching `valueLabels` entry.
Icon	`<span>` × 2	A faint base icon with a filled copy on top, clipped to the fill amount.
Value text	`<span>`	With `showValue`: the number, e.g. `4.5`.
Value label	`<span aria-hidden>`	With `valueLabels`: the label for the hovered or selected value.
Read-only root	`<div role="img">`	With `isReadOnly`: not focusable, named "4.5 out of 5".

Examples

Read-only with half stars

isReadOnly renders a static display. Fractional values round to the nearest half, so 4.3 shows four and a half stars. Pair it with the numeric average and the review count.

4.5

1,188 reviews

5812
4264
371
218
123

import { Rating } from "@/components/ui/rating";

const breakdown = [
  { stars: 5, count: 812 },
  { stars: 4, count: 264 },
  { stars: 3, count: 71 },
  { stars: 2, count: 18 },
  { stars: 1, count: 23 },
];
const total = breakdown.reduce((n, b) => n + b.count, 0);

export default function RatingReadOnly() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <div className="flex items-end gap-3">
        <span className="font-semibold text-4xl tabular-nums leading-none">
          4.5
        </span>
        <div className="flex flex-col gap-1">
          <Rating isReadOnly value={4.5} size="sm" />
          <span className="text-muted-foreground text-xs">
            {total.toLocaleString()} reviews
          </span>
        </div>
      </div>
      <ul className="flex flex-col gap-1.5 text-xs">
        {breakdown.map((b) => (
          <li key={b.stars} className="flex items-center gap-2">
            <span className="w-3 text-muted-foreground tabular-nums">
              {b.stars}
            </span>
            <span className="h-1.5 flex-1 overflow-hidden rounded-full bg-muted">
              <span
                className="block h-full rounded-full bg-warning"
                style={{ width: `${(b.count / total) * 100}%` }}
              />
            </span>
            <span className="w-8 text-right text-muted-foreground tabular-nums">
              {b.count}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}

Sizes

sm (16px), md (20px, default) and lg (28px).

import { Rating } from "@/components/ui/rating";

export default function RatingSizes() {
  return (
    <div className="flex flex-col gap-4">
      <Rating aria-label="Small rating" size="sm" defaultValue={3} />
      <Rating aria-label="Medium rating" size="md" defaultValue={3} />
      <Rating aria-label="Large rating" size="lg" defaultValue={3} />
    </div>
  );
}

Custom icon and color

Pass any icon to icon and a tone to color (default warning). Use maxValue for a shorter scale.

import { FlameIcon, HeartIcon } from "lucide-react";
import { Rating } from "@/components/ui/rating";

export default function RatingCustomIcon() {
  return (
    <div className="flex flex-col gap-5">
      <Rating
        label="How much did you love it?"
        icon={<HeartIcon />}
        color="danger"
        defaultValue={4}
      />
      <Rating
        label="Spice level"
        icon={<FlameIcon />}
        color="warning"
        maxValue={3}
        defaultValue={2}
        valueLabels={["Mild", "Medium", "Hot"]}
      />
    </div>
  );
}

Value labels

valueLabels names each value. The names are used as each radio's accessible name and shown next to the icons for the hovered or selected value.

import { useState } from "react";
import { Rating } from "@/components/ui/rating";

export default function RatingValueLabels() {
  const [value, setValue] = useState(0);
  return (
    <div className="flex flex-col gap-2">
      <Rating
        label="Rate this article"
        value={value}
        onChange={setValue}
        valueLabels={[
          "Not helpful",
          "Slightly helpful",
          "Helpful",
          "Very helpful",
          "Exactly what I needed",
        ]}
      />
      <p className="text-muted-foreground text-xs">
        {value ? `You rated ${value} of 5.` : "No rating yet."}
      </p>
    </div>
  );
}

In a form

Ratings work like any React Aria field: name submits the value with the form, isRequired blocks submission until a value is chosen, and errorMessage customizes the message.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Rating } from "@/components/ui/rating";
import { TextareaField } from "@/components/ui/textarea";

export default function RatingForm() {
  const [sent, setSent] = useState<string | null>(null);
  return (
    <Form
      className="flex w-full max-w-sm flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        setSent(`Thanks! You gave ${data.get("rating")} stars.`);
      }}
    >
      <Rating
        name="rating"
        label="Overall experience"
        isRequired
        errorMessage="Choose a rating before submitting."
      />
      <TextareaField name="comment" label="What could we improve?" />
      <Button type="submit" className="self-start">
        Submit review
      </Button>
      {sent && (
        <p role="status" className="text-muted-foreground text-sm">
          {sent}
        </p>
      )}
    </Form>
  );
}

Accessibility

Interactive ratings are a React Aria RadioGroup with one radio per value. Tab moves focus into the group; Left and Right arrows (Up and Down too) change the value, and each change is announced.
Every radio has a name: "3 of 5" by default, or the matching valueLabels entry, such as "Helpful".
Name the group with label, aria-label or aria-labelledby.
The read-only display is a single role="img" element named "4.5 out of 5", prefixed with label when you pass one. It isn't focusable.
Filled and empty icons differ in fill, not only color, so the value reads in high-contrast and grayscale modes.
Clicking the selected star clears the rating (value 0); from the keyboard, Backspace or Delete clears it. Turn this off with allowClear={false}, for example when a rating is required.

Styling

Data attributes

Attribute	On	Present when
`data-slot="rating"`	Root	Always
`data-readonly`	Root	`isReadOnly`
`data-slot="rating-icon"`	Each icon	Always
`data-slot="rating-value"`	Value text	`showValue`

The root also gets React Aria's RadioGroup attributes (data-disabled, data-invalid, data-required, …) and sets the group/field group, like other fields.

Tone variables

color sets --tone on the root. Filled icons use text-(--tone); empty icons use text-(--tone)/20 in light mode and text-muted-foreground/30 in dark mode.

API Reference

Prop

Type

Also accepts the props of React Aria's RadioGroup except orientation, such as isInvalid, validate and aria-describedby.

Radio Group: choices with written labels.
Slider: a value on a fine-grained scale.
Textarea: pair a rating with a written review.