Inputs/Rating

Rating

Display and collect star ratings with half-star precision and custom icons.

Themed

When to Use

Use Rating when you need to:

Display average product or service ratings in a visual format
Collect user feedback as a star-based score (e.g., product reviews)
Show aggregated review scores with total count
Provide a quick visual indicator of quality or satisfaction
Compare items side-by-side using a consistent visual scale

When Not to Use

Continuous numeric input - use Slider for range-based values
Precise numeric entry - use Input with type="number" instead
Task completion indicators - use Progress for percentage-based displays
Binary feedback (like/dislike) - use a simple toggle button or thumbs up/down

Default

The default read-only rating display with 5 stars.

Sizes

Available size options: sm, md (default), lg.

Small

Medium (default)

Large

Read-Only Display

Display ratings without user interaction. Perfect for showing product ratings, reviews, or scores.

Interactive Rating

Allow users to select a rating. Hover to preview, click to set. Set readonly=false to enable.

Selected rating: 0

Half-Star Precision

Display and select half-star ratings for more granular feedback (0.5, 1.5, 2.5, etc.).

Half stars enabled (default)

Half stars disabled

With Rating Count

Show the numeric rating value and total number of reviews.

4.5

4.2(234 reviews)

3.8(1,523 ratings)

(42 reviews)

Custom Icons

Use custom icons like hearts, thumbs, or any lucide icon instead of stars.

Hearts

Thumbs Up

Custom Colors

Customize fill and empty colors using design tokens or Tailwind classes.

Primary (default)

Destructive

Secondary

Custom (green)

UX & Design Guidelines

Visual Hierarchy

Use the default fillColor (primary) for standard product ratings. Reserve text-destructive fill for negative sentiment indicators. Pair ratings with showValue and count to provide full context and reduce ambiguity.

Spacing & Layout

When placing ratings alongside text content, use gap-2 or gap-3 for comfortable spacing. For lists of rated items, align all rating components to a consistent horizontal position so users can scan and compare values quickly. Keep the numeric value and count close to the stars for clear association.

Responsive Behavior

On mobile, use size="lg" for interactive ratings to provide adequate touch targets (minimum 44x44px per star). For read-only display in compact layouts, size="sm" works well alongside product cards. Consider hiding the count text on very small screens and showing only the numeric value.

Color & Contrast

The default text-primary fill-primary fill color provides strong contrast against both light and dark backgrounds. Empty stars use text-muted for a subtle but visible unfilled state. When using custom colors, ensure a minimum 3:1 contrast ratio between filled and empty states for distinguishability.

Accessibility

Keyboard Navigation

Tab — Move focus to/from the rating component
Arrow Left / Arrow Right — Decrease or increase rating by one star (interactive mode)
Home — Set rating to minimum value (interactive mode)
End — Set rating to maximum value (interactive mode)

Screen Reader Support

The component uses role="img" with an aria-label that announces the current rating (e.g., "Rating: 4.5 out of 5 stars")
When showValue and count are provided, screen readers can access the full context
Interactive ratings should include a visible label using aria-labelledby or wrapping in a labeled group
Read-only ratings are announced as images, preventing unintended interaction

Focus Management

In interactive mode, the rating component should receive focus as a single unit rather than individual stars. Visible focus indicators use focus-visible:ring-[3px] to meet WCAG 2.1 Level AA requirements. Read-only ratings are not focusable and are skipped in the tab order.

Touch Targets

Each star in interactive mode acts as a click target. Use size="lg" (24px icons) for touch interfaces to meet the 44x44px minimum touch target recommendation. Half-star precision divides each star into two hit zones, so larger sizes are especially important for accurate half-star selection.

ARIA Attributes

{/* Read-only display rating */}
<Rating
  value={4.5}
  readonly
  aria-label="Product rating: 4.5 out of 5 stars"
/>

{/* Interactive rating with accessible label */}
<div role="group" aria-labelledby="rating-label">
  <label id="rating-label">Rate this product</label>
  <Rating
    value={rating}
    readonly={false}
    onChange={setRating}
    aria-label={`Rating: ${rating} out of 5 stars`}
  />
</div>

{/* Rating with visible count for context */}
<Rating
  value={4.2}
  readonly
  showValue
  count={234}
  aria-label="Average rating: 4.2 out of 5 stars, based on 234 reviews"
/>

API Reference

The Rating component accepts the following props in addition to standard div attributes.

Prop	Type	Default	Description
value	`number`	0	Current rating value (0-max, supports half stars with 0.5 increments).
max	`number`	5	Maximum rating value (number of stars to display).
size	`"sm" \| "md" \| "lg"`	"md"	The size of the rating stars.
readonly	`boolean`	true	Whether the rating is read-only (display only) or interactive.
onChange	`(value: number) => void`	—	Callback fired when rating changes (only works when readonly=false).
allowHalf	`boolean`	true	Whether to allow half-star ratings (0.5 precision).
icon	`React.ComponentType`	Star	Custom icon component to use instead of the default Star icon.
fillColor	`string`	"text-primary fill-primary"	Tailwind classes for the filled star color.
emptyColor	`string`	"text-muted"	Tailwind classes for the empty star color.
showValue	`boolean`	false	Whether to display the numeric rating value next to the stars.
count	`number`	—	Total number of ratings/reviews to display (e.g., '234 reviews').
countText	`string`	"reviews"	Custom text to display after the count number.
className	`string`	—	Additional CSS classes to apply to the root element.