Rating

A compound star rating control. Rating manages the value and size; RatingButton renders each star, so you control how many stars appear and can swap in any icon.

Installation

npx shadcn@latest add @iconiq/rating

File Structure

Usage

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

export function RatingPreview() {
  return (
    <Rating defaultValue={3}>
      <RatingButton />
      <RatingButton />
      <RatingButton />
      <RatingButton />
      <RatingButton />
    </Rating>
  );
}

Props

Props
Description

Rating

children

One RatingButton per star. Their count is the scale.

Type ReactNode

value

Controlled rating value. Pair with onValueChange.

Type number

defaultValue

Initial rating for uncontrolled usage.

Type number·Default 0

onValueChange

Called with the new value on click or arrow key.

Type (value: number) => void

onChange

Lower-level change handler that also receives the originating mouse or keyboard event.

Type (event, value: number) => void

readOnly

Renders every RatingButton as a native disabled button, for showing an existing rating without interaction.

Type boolean·Default false

size

Icon size in pixels for all RatingButton children. Individual buttons can override with their own size prop.

Type number·Default 20

className

Optional class names applied to the root element.

Type string

RatingButton

icon

Icon element to render. Swap in any icon — a Lucide icon or a custom SVG — as long as it accepts size and className.

Type ReactElement·Default <StarIcon />

size

Icon size in pixels, forwarded to the icon element. Falls back to the parent Rating's size (default 20).

Type number

className

Optional class names applied to the button.

Type string

index

Position in the scale. Injected automatically by Rating from child order — you don't need to pass it yourself.

Type number

Motion behavior

Each star bounces through a couple of visible oscillations as it crosses the filled threshold, with a color fade underneath and a per-star stagger that ripples the effect across the row.

Scale animates through a deliberately underdamped Motion spring, so it swings past its resting size a few times before settling — a real bounce, not a single overshoot.

Color still fades with a plain CSS transition, layered underneath the spring so the fill change reads as smooth rather than an abrupt swap.

Each star's spring is delayed by its index, so hovering across the row or jumping several values at once ripples left to right instead of popping all at once.

Hover adds its own quick scale-up, and tap adds a scale-down, independent of the fill animation, for tactile feedback while scanning the row.

When prefers-reduced-motion is set, every spring and stagger is skipped and stars snap directly to their resting scale.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @radix-ui/react-use-controllable-state, motion.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.