BetaBuilt on Vercel’s UI SDK 0.1.0-beta.1. Its API may change.

Rating

A star rating on Vercel's UI SDK with whole or half stars, a hover preview, read-only averages and form support.

Form components
2 parts
10 examples
Updated Nov 13, 2026

Depends on

@tabler/icons-react
@ui-sdk/core
@ui-sdk/react
class-variance-authority

"use client"

import * as React from "react"

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

const labels = ["Terrible", "Poor", "Okay", "Good", "Great"]

function UiSdkRatingDemo() {
  const [value, setValue] = React.useState<number | null>(4)

  return (
    <div className="flex flex-col items-center gap-2">
      <Rating
        aria-label="How was your stay?"
        size="lg"
        value={value}
        onValueChange={setValue}
        getValueLabel={(score, max) =>
          labels[score - 1] + ", " + score + " of " + max
        }
      >
        <RatingItem />
      </Rating>
      <p
        aria-hidden="true"
        className="min-h-5 text-sm text-muted-foreground tabular-nums"
      >
        {value ? labels[value - 1] : "Not rated yet"}
      </p>
    </div>
  )
}

export { UiSdkRatingDemo }

Installation

pnpm dlx shadcn@latest add https://hextaui.com/r/ui-sdk-rating.json

Adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

Add the theme tokens to your global CSS, if you haven’t yet.

Install the dependencies.

pnpm add @ui-sdk/react@0.1.0-beta.1 @ui-sdk/core@0.1.0-beta.1 @tabler/icons-react class-variance-authority cn

3
Copy and paste the following code into your project.
components/ui/ui-sdk-rating.tsx
"use client" import * as React from "react" import { IconStarFilled } from "@tabler/icons-react" import * as RatingPrimitive from "@ui-sdk/react/rating" import { cva, type VariantProps } from "class-variance-authority" import { cn } from "cn"
Update the import paths to match your project setup.

Usage

UI SDK adds a little CSS of its own in a cascade layer named ui-sdk. Declare that layer at the top of your global stylesheet, above the Tailwind import, so your classes win over it.

@layer ui-sdk;

@import "tailwindcss";

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

<Rating aria-label="Rating" defaultValue={3}>
  <RatingItem />
</Rating>

Rating renders its child once per star, so put one RatingItem inside it. Each star draws an empty star with a filled one clipped to --rating-fill, so half stars and averages like 4.3 show exactly.

Composition

Rating
└── RatingItem

Examples

Half stars

Open example

With step={0.5}, each half of a star is its own radio, and the arrow keys move by half a star.

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingHalf() {
  return (
    <Rating aria-label="Rating" step={0.5} defaultValue={3.5}>
      <RatingItem />
    </Rating>
  )
}

export { UiSdkRatingHalf }

Read-only

Open example

A read-only rating is one image named by getValueLabel, and it shows any score, like an average.

"use client"

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingReadOnly() {
  return (
    <div className="flex items-center gap-2 text-sm">
      <Rating
        readOnly
        size="sm"
        value={4.3}
        getValueLabel={(value, max) =>
          "Rated " + value + " out of " + max + " stars"
        }
      >
        <RatingItem />
      </Rating>
      <span className="font-medium tabular-nums">4.3</span>
      <span className="text-muted-foreground">(1,284 reviews)</span>
    </div>
  )
}

export { UiSdkRatingReadOnly }

Sizes

Open example

size is sm, default or lg.

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Rating aria-label="Small rating" size="sm" defaultValue={3}>
        <RatingItem />
      </Rating>
      <Rating aria-label="Default rating" defaultValue={3}>
        <RatingItem />
      </Rating>
      <Rating aria-label="Large rating" size="lg" defaultValue={3}>
        <RatingItem />
      </Rating>
    </div>
  )
}

export { UiSdkRatingSizes }

Deselectable

Open example

With deselectable, pressing the checked star again clears the score.

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingDeselectable() {
  return (
    <Rating aria-label="Rating" deselectable defaultValue={2}>
      <RatingItem />
    </Rating>
  )
}

export { UiSdkRatingDeselectable }

Controlled

Open example

Pass value and onValueChange, where null means no score yet. A controller from createRatingController() sets the score from anywhere.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import {
  createRatingController,
  Rating,
  RatingItem,
} from "@/components/ui/ui-sdk-rating"

function UiSdkRatingControlled() {
  const [rating] = React.useState(createRatingController)
  const [value, setValue] = React.useState<number | null>(null)

  return (
    <div className="flex flex-col items-center gap-3">
      <Rating
        aria-label="Rating"
        controller={rating}
        value={value}
        onValueChange={setValue}
      >
        <RatingItem />
      </Rating>
      <div className="flex gap-2">
        <Button variant="outline" size="sm" onClick={() => rating.setValue(5)}>
          Rate 5
        </Button>
        <Button
          variant="ghost"
          size="sm"
          disabled={value === null}
          onClick={() => setValue(null)}
        >
          Clear
        </Button>
      </div>
      <p className="text-sm text-muted-foreground tabular-nums">
        {value === null ? "No score" : "Score: " + value}
      </p>
    </div>
  )
}

export { UiSdkRatingControlled }

Form

Open example

With a name, the score submits with the form. required blocks submission until there’s a score, with the browser’s own message.

"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingForm() {
  const [submitted, setSubmitted] = React.useState<string | null>(null)

  return (
    <form
      className="flex flex-col items-start gap-3"
      onSubmit={(event) => {
        event.preventDefault()
        setSubmitted(String(new FormData(event.currentTarget).get("score")))
      }}
      onReset={() => setSubmitted(null)}
    >
      <div className="flex flex-col gap-1.5">
        <span id="rating-form-label" className="text-sm font-medium">
          Rate this answer
        </span>
        <Rating aria-labelledby="rating-form-label" name="score" required>
          <RatingItem />
        </Rating>
      </div>
      <div className="flex gap-2">
        <Button type="submit" size="sm">
          Submit
        </Button>
        <Button type="reset" variant="outline" size="sm">
          Reset
        </Button>
      </div>
      <p role="status" className="text-sm text-muted-foreground">
        {submitted ? "Submitted score=" + submitted : "Nothing submitted yet."}
      </p>
    </form>
  )
}

export { UiSdkRatingForm }

Custom icon

Open example

Pass your own icon as the child of RatingItem and switch it with data-filled. tone sets the color.

import { IconHeart, IconHeartFilled } from "@tabler/icons-react"

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingCustomIcon() {
  return (
    <Rating
      aria-label="How much did you like it?"
      defaultValue={3}
      tone="destructive"
    >
      <RatingItem>
        <IconHeart
          aria-hidden="true"
          className="size-6 group-data-[filled]/rating-item:hidden group-data-[partial]/rating-item:hidden"
        />
        <IconHeartFilled
          aria-hidden="true"
          className="hidden size-6 group-data-[filled]/rating-item:block group-data-[partial]/rating-item:block"
        />
      </RatingItem>
    </Rating>
  )
}

export { UiSdkRatingCustomIcon }

Disabled

Open example

A disabled rating can’t be focused or changed, and submits nothing.

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingDisabled() {
  return (
    <Rating aria-label="Rating" disabled defaultValue={3}>
      <RatingItem />
    </Rating>
  )
}

export { UiSdkRatingDisabled }

Right to left

Open example

Stars run from the right, and a half star fills from its right edge.

import { Rating, RatingItem } from "@/components/ui/ui-sdk-rating"

function UiSdkRatingRtl() {
  return (
    <div dir="rtl">
      <Rating aria-label="التقييم" step={0.5} defaultValue={2.5}>
        <RatingItem />
      </Rating>
    </div>
  )
}

export { UiSdkRatingRtl }

Keyboard

Key	Action
`Tab`	Moves into the rating, onto the checked star or the first one.
`←→↑↓`	Moves to the next or previous score and checks it, stopping at the ends unless loop is set.
`Space`	Checks the focused star, or clears it when it’s checked and the rating is deselectable.
`Enter`	Submits the form.

Accessibility

A rating is a radio group with one tab stop. Each star holds one radio per score it can pick, named by getValueLabel, so name scores in words people use, like “Great, 5 of 5”. The star icons are hidden from screen readers. A read-only rating is a single image instead.

Stars only grow on hover and shrink on press when motion is allowed. On touch screens each star gets extra padding, and in forced colors mode filled stars use the text color and empty ones use the system’s gray.

API reference

Each part wraps the UI SDK part of the same name and accepts all of its props, including render and a className that can be a function of the part’s state.

Rating

Prop	Type	Default
`value`	`number \| null`	`–`
`defaultValue`	`number \| null`	`–`
`onValueChange`	`(value: number \| null, details) => void`	`–`
`max`	`number`	`5`
`step`	`number`	`1`
`size`	`"sm" \| "default" \| "lg"`	`"default"`
`tone`	`"default" \| "neutral" \| "destructive"`	`"default"`
`deselectable`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`disabled`	`boolean`	`false`
`required`	`boolean`	`false`
`name`	`string`	`–`
`loop`	`boolean`	`false`
`getValueLabel`Names each score for its radio, and a read-only rating.	`(value: number, max: number) => string`	`–`
`controller`From createRatingController().	`RatingController`	`–`

Attribute	Description
`data-slot="rating"`	Target the rating in CSS.
`data-size`	The size: sm, default or lg.
`data-tone`	The tone: default, neutral or destructive.
`data-readonly`	Present when read-only.
`data-disabled`	Present when disabled.
`--rating-color`	The color of filled stars, set by tone.

RatingItem

Prop	Type	Default
`children`The star’s icon. Defaults to a Tabler star that fills by --rating-fill.	`ReactNode`	`–`
`render`	`ReactElement \| (props, state) => ReactElement`	`–`

Attribute	Description
`data-slot="rating-item"`	Target a star in CSS.
`data-filled`	Present on stars the shown score covers whole.
`data-partial`	Present on the star the shown score covers part of.
`data-checked`	Present on the star the score ends in.
`data-highlighted`	Present on the stars up to the score a pointer previews.
`--rating-fill`	How much of the star the shown score covers, from 0 to 1.