Rating

Description

Rating is a Create UI Pro component — installing it requires a Pro seat. It captures or displays a score out of a small set of items. Interactive ratings are built on the Radix RadioGroup primitive — the group is a role="radiogroup" of role="radio" items, so selecting a value is fully keyboard accessible. Read-only ratings render as a single labelled role="img" instead of a control.

Reach for it whenever a value maps to a handful of discrete steps: a product review (star), a favourite or like scale (heart), a satisfaction survey (emoji), or a plain numeric scale (number). Drive interactive ratings with value/onValueChange (or defaultValue for uncontrolled), and pass readOnly with a value — including fractional values like 4.5 — to show an existing score.

Don't use Rating for a continuous value along a range (use Slider) or for a single on/off choice in a form (use Radio Group). For a non-interactive completion indicator, use Progress.

Installation

Rating is part of Create UI Pro; adding it requires an authenticated Pro seat.

pnpm dlx @create-ui/cli add rating

Usage

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

<Rating defaultValue={3} />

Examples

Types

type chooses the glyph. star (default) and heart fill cumulatively; emoji highlights a single mood; number fills up to the selected digit. Pass a custom set of faces to emojis to override the emoji scale.

Variants

variant sets the color of the filled glyph. colorful (default) uses each type's natural color (gold star, rose heart); primary tints it with the product color; neutral uses a solid dark tone.

Appearance

appearance controls the star/heart fill. filled (default) is a solid glyph; outline is a stroked glyph whose interior fills on selection.

Shape

shape sets the corner style of the star/heart glyph. sharp (default) has crisp points; rounded softens them. It applies to both filled and outline appearances.

Sizes

size scales the glyphs. Two steps, xs and md (default). When a container is set, the box scales with the size too.

Containers

container wraps each item in a box. none (default) is a bare glyph; rounded is a rounded square; circle is a full circle. The box background and border reflect the active state.

Fractional and precision

Read-only ratings render fractional values exactly — value={4.2} fills the fifth star 20%. Set precision="half" to snap the display to the nearest half step. Precision applies to read-only ratings only; interactive selection is always whole-step.

Animation

animation sets how the star/heart fill transitions on hover and selection. sweep (default) reveals the color by width, left to right; fade pops each glyph in with a spring scale and opacity fade. Hover the stars to preview.

Review summary

Compose RatingSummary with RatingSummaryScore, RatingSummaryReviews, and RatingSummaryDot (a subtle • separator) — plus any Avatar, AvatarGroup, or Badge — into a compact review block. Use layout="stacked" to split it across two rows (score + badge over reviewers + a reviews link), and tint (primary, neutral-soft, neutral-outline, yellow) with shape (rounded or pill) for a colored container. Inside a tinted container the reviews link steps down to a neutral tone so it sits calmly on the fill. RatingSummary shares its size with the score, reviews, and dot via context.

PreviewCode

Copy

3.6/ 5.0Top Rated

+7

2,341 reviews

3.6/ 5.0Top Rated

+7

2,341 reviews

3.6/ 5.0

+7

3.6/ 5.0Top Rated

3.6/ 5.0•2,341 reviews

3.6/ 5.0

Accessibility

Interactive ratings are built on the Radix RadioGroup primitive, so they follow the WAI-ARIA radiogroup pattern: the group is role="radiogroup", each item is role="radio", and focus uses a roving tabindex — one tab stop for the whole group, arrow keys move between items.

ARIA notes:

• Each item has an aria-label describing its value (e.g. 3 stars). Pass an aria-label to the root to describe what is being rated.
• Read-only and disabled ratings render a single role="img" with an aria-label like Rated 4 out of 5; the individual glyphs are aria-hidden and the rating is not focusable.
• Pass name to submit the selected value inside a form.

Styling

Tailwind override: pass className to merge Tailwind classes with the component's classes (via cn()):

<Rating className="gap-2" defaultValue={3} />

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="rating" on the root, data-slot="rating-item" on each item, data-slot="rating-glyph" on the glyph inside it.
• data-slot="rating-summary", data-slot="rating-summary-score", data-slot="rating-summary-reviews", data-slot="rating-summary-dot" on the summary parts.
• data-type="<type>", data-variant="<variant>", data-appearance="<appearance>", data-shape="<shape>", data-container="<container>", data-size="<size>" on the root.

Target a specific state in CSS:

[data-slot="rating"][data-type="heart"] {
  /* … */
}

Related Components

• Radio Group: the underlying single-select primitive; use it for general single-choice form fields.
• Slider: use this to pick a value along a continuous range instead of discrete steps.
• Progress: non-interactive indicator for how far a known task has advanced.

API Reference

Rating

Star / heart / emoji / number rating. Interactive by default (a Radix RadioGroup); pass readOnly or disabled to render a static role="img". Extends React.ComponentProps<"div"> (minus onChange, defaultValue, and dir).

Props

Variants

RatingItem

A single, standalone rating glyph for static display (e.g. a lone star with a score). Renders a <span>; sizing and appearance props mirror Rating.

Props

RatingSummary

Layout wrapper for a review block. Shares its size with RatingSummaryScore, RatingSummaryReviews, and RatingSummaryDot via context, and drops in any Rating, Avatar, or Badge. Renders a <div>.

Props

RatingSummaryScore

Renders the numeric score as value / max (e.g. 4.5 / 5.0). Reads size from RatingSummary when not set.

Props

RatingSummaryReviews

Renders the review count as a link. Falls back to {count} reviews when no children are given, and formats the count with thousands separators. With an href it is a real link; without one it renders as styled text. In an untinted summary it uses the primary link color; inside a tinted RatingSummary it switches to the neutral tone. Reads size from RatingSummary when not set.

Props

RatingSummaryDot

A small • separator for review rows — e.g. between the score and the review count. Purely decorative (aria-hidden), and its text scales with the summary size (xs → text-paragraph-xs, md → text-paragraph-md). Reads size from RatingSummary when not set. Renders a <span>.

Props