Rating

An accessible rating component with half-value support, keyboard navigation, and form integration.

Installation

CLI

Dependencies

This component requires the following npm packages:

Registry Dependencies

This component also requires: https://ui.shadcn.com/r/styles/base-vega/utils.json

Usage

Rating is an accessible star rating component that allows users to provide ratings with support for half values, keyboard navigation, and form integration.

It supports both controlled and uncontrolled modes, RTL layouts, multiple size variants, and custom icons. The component is fully accessible with proper ARIA attributes and keyboard navigation.

Basic Rating

Half Steps (LTR)

Half Steps (RTL)

Examples

Controlled State

Use value andonValueChange to control the rating value programmatically.

Current rating: 3

Half Steps

Set step={0.5} to enable half-star ratings. Click on the left or right half of a star to select half values.

Themes & Custom Icons

Customize the rating with different colors and icons by passing custom children to RatingItem.

Default

Gold

Heart

Energy

Sizes

Use the size prop to change the size of rating items.

Small

Default

Large

API Reference

Rating Props

Prop	Type	Default	Description
`value`	`number`	-	Controlled rating value.
`defaultValue`	`number`	`0`	Default rating value (uncontrolled).
`onValueChange`	`(value: number) => void`	-	Callback fired when the rating value changes.
`onHover`	`(value: number \| null) => void`	-	Callback fired when hovering over a rating item.
`max`	`number`	`5`	Maximum rating value.
`step`	`0.5 \| 1`	`1`	Step increment for ratings. Use 0.5 for half-star ratings.
`activationMode`	`"automatic" \| "manual"`	`"automatic"`	How items are activated. "automatic" selects on focus, "manual" requires Enter/Space.
`dir`	`"ltr" \| "rtl"`	-	Text direction for RTL support.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout orientation of rating items.
`size`	`"sm" \| "default" \| "lg"`	`"default"`	Size variant for rating items.
`clearable`	`boolean`	`false`	Allow clearing the rating by clicking the current value.
`disabled`	`boolean`	`false`	Disable all rating items.
`readOnly`	`boolean`	`false`	Make the rating read-only.
`required`	`boolean`	`false`	Mark the rating as required for form validation.
`name`	`string`	-	Name attribute for form submission.
`asChild`	`boolean`	`false`	Render as child element using Radix Slot.

RatingItem Props

Prop	Type	Default	Description
`index`	`number`	-	Item index (0-based). Auto-assigned if not provided.
`children`	`ReactNode \| ((dataState: DataState) => ReactNode)`	-	Custom content. Receives dataState for conditional rendering. Defaults to Star icon.
`asChild`	`boolean`	`false`	Render as child element using Radix Slot.

Accessibility

The Rating component follows WAI-ARIA guidelines for radio groups and includes full keyboard navigation support.

Keyboard Interactions

Key	Description
`ArrowLeft` / `ArrowRight`	Navigate between rating items
`Home`	Move to first rating item
`End`	Move to last rating item
`Enter` / `Space`	Activate focused item (manual mode)