Rating

Choose one answer from a compact visual or numeric scale.

Preview

Design guidance

Rating uses Base UI's radio group and hidden native radio inputs. Tab enters the group, Arrow keys move between options, and Space selects. Hover previews glyph fill without committing the value. Provide a clear group label with aria-label or an owning Field. Use readOnly for review states and disabled when the answer cannot be changed.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/rating.json

Basic usage

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

<Rating.Root name="delivery" defaultValue={3} aria-label="How was your delivery?" />

Structures

Examples

Basic star

Choose one of five scores. Stars fill through the selected value.

Number

Choose a score from one to five.

Custom icon

Use a custom icon for each score and caller-owned response text.

Emoji

Choose the face that best matches your response.

NPS 0–10

Zero is a real answer. Leave the group unanswered with value={null} when no response exists.

Seven-point linear scale

Choose confidence from one to seven.

Five-point opinion scale

Rate agreement with a statement from one to five.

CSAT satisfaction emoji

Choose a satisfaction emoji. Hover or focus to see its meaning in a tooltip.

Half star

Choose half-point scores. Each half has its own accessible radio value and keyboard stop.

Half custom icon

Use the same half-point behavior with a caller-owned icon.

Visible description

Descriptions appear in a Tooltip by default. Set showDescription to keep feedback visible beside the choices on larger screens and below them on small screens.

Outlined choices

Add a subtle boundary to each number or emoji. Selection keeps its small inner surface.

API reference

Rating properties
Prop	Type	Default	Description
`precision`	`1 \| 0.5`	`1`	Half increments for built-in star/custom scales. Explicit options stay authoritative; categorical variants retain their choices.
`icon / renderIcon`	`ReactNode / (option, state) => ReactNode`		Custom glyph or per-option renderer. State exposes selected and previewed.
`getDescription`	`(option) => ReactNode`		Caller response text for Tooltips or opted-in inline feedback.
`required`	`boolean`	`false`	Requires a selected answer for native form validation.
`variant`	`"star" \| "number" \| "custom" \| "emoji" \| "nps" \| "linear" \| "opinion" \| "csat"`		Selects the built-in scale.
`value / defaultValue`	`number \| null`		Controlled or initial answer. Null is unanswered; NPS 0 remains selected.
`appearance`	`"ghost" \| "outline"`		Default ghost. Outline adds a subtle edge to individual categorical choices; stars and custom glyphs stay borderless.
`startLabel / endLabel`	`ReactNode`		Endpoint labels for numeric scales. Defaults match the built-in question; pass null to omit.
`showDescription`	`boolean`		Opt into small inline feedback. Default false uses a Tooltip on each option; visible feedback moves below the items on small screens.
`options`	`readonly RatingOption[]`		Replaces the built-in options with caller-owned values and labels.
`readOnly / disabled`	`boolean`		Keeps the native radio semantics while preventing changes when true.
`name / form`	`string`		Connects the hidden native radio inputs to FormData.
`onValueChange`	`(value, eventDetails) => void`		Runs after a user selects an option.

The ref points to the outer div. RadioGroup attributes and events are forwarded to the group. Explicit empty options render no answers. Unknown values remain unanswered. Labels and business validation belong to the caller.