Rating React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Rating is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Rating from @/components/ui/rating.

import { useState } from "react"
import { Rating } from "@/components/ui/rating"

const LABELS = ["Very poor", "Poor", "Okay", "Good", "Excellent"]

export function SellerReview() {
  const [rating, setRating] = useState(0)
  return (
    <div className="flex flex-col gap-6">
      <Rating
        label="How was your experience?"
        name="rating"
        value={rating}
        onValueChange={setRating}
        labels={LABELS}
        showLabel
        emptyLabel="Tap a star"
        required
      />
      <Rating readOnly value={4.8} tone="warning" size="sm" showValue />
    </div>
  )
}

Props

• labeldefault ""
  ReactNode

  The field label, rendered as a span that names the icon group (a click on it focuses the group).

• descriptiondefault ""
  ReactNode

  Helper text under the icons, linked with aria-describedby. The error takes its place while it shows.

• errordefault ""
  ReactNode

  Replaces the description with the animated error, tints the empty icons red and sets aria-invalid.

• requireddefault false
  boolean

  The required mark after the label. The check itself belongs to your form (the playground blocks sending without a rating).

• invaliddefault false
  boolean

  The invalid look (red-tinted empty icons) and aria-invalid without a message.

• disableddefault false
  boolean

  Dims to 50%, leaves the tab order and ignores pointer and keys. A disabled FieldGroup disables it too.

• readOnlydefault false
  boolean

  Display only: role="img" with a spoken summary, no pointer or keys, and fractions like 4.3 drawn proportionally. The number keeps one decimal ("4,8").

• maxdefault 5
  number

  How many icons. Below 1 falls back to 5. The playground keeps its Romanian labels only at 5.

• allowHalfdefault false
  boolean

  Half values: the left half of an icon (right half in RTL) gives x.5, and the arrow keys move by 0.5. Ignored with icons.

• clearabledefault true
  boolean

  Choosing the current value again clears it, a scrub past the first icon clears, and 0 / Backspace / Delete clear from the keyboard. false keeps at least one step.

• sizedefault "md"
  "sm" | "md" | "lg"

  Icons 16 / 24 / 32px with 2 / 4 / 6px between them, and the value and label type. On touch screens every icon is a 44px target.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The fill. neutral is black in light mode and white in dark mode; warning gives the classic amber stars.

• colordefault ""
  string

  Any CSS color for the fill; replaces the tone.

• showLabeldefault false
  boolean

  The hovered or chosen value's label beside the icons (Very poor … Excellent). Needs labels.

• emptyLabeldefault ""
  ReactNode

  What the label slot says while nothing is chosen, with showLabel. Empty shows nothing.

• showValuedefault false
  boolean

  The number beside the icons, through Intl: "4.5" in en-US, "4,5" in de-DE. It follows the hover preview.

• localedefault ""
  string

  Locale for the number. Empty uses the UIProvider locale, then the nearest LocaleProvider, then the page's language (en-US on the server). The demo passes en-US.

• namedefault ""
  string

  Form field name: a hidden input submits the value ("0" when empty, "4.5" with halves), and a form reset puts defaultValue back.

• icondefault "<Star />"
  ReactNode

  The icon repeated max times: any lucide icon (Heart, ThumbsUp). The fill layer paints it with fill-current.

• icons
  ReactNode[]

  One icon per value, e.g. Frown, Meh, Smile, Laugh. Only the chosen (or hovered) icon lights up, in the tone with a soft tone fill; no halves. A list shorter than max repeats its last icon.

• labels
  string[]

  One label per value (labels[0] is 1). Read as aria-valuetext and shown with showLabel.

• getValueTextdefault "(v, m) => `${v} of ${m}`"
  (value: number, max: number) => string

  What screen readers hear for a value without a label (and for halves).

• getReadOnlyLabeldefault "(v, m) => `Rated ${v} of ${m}`"
  (value: number, max: number) => string

  The spoken name of a read-only rating; the value is rounded to one decimal.

• value
  number

  The controlled rating; 0 = none. A value between steps (4.3) is drawn proportionally and snaps on the next interaction.

• defaultValuedefault 0
  number

  The uncontrolled start; a form reset returns to it. The playground starts its rating here.

• onValueChange
  (value: number) => void

  When a rating is committed: on release of a tap or scrub, and on every key press.

• id
  string

  The group's id. Defaults to useId(); the label points at it.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• classNames
  Partial<Record<"box" | "root" | "item" | "icon" | "fill" | "empty" | "value" | "label" | "field" | "description" | "error", string>>

  Extra classes for the inner parts: box (icons, number and label), root (the slider group), item (each cell), icon (the icon box), fill and empty (the two layers), value, label and the field parts.

• className
  string

  Classes for the outermost element: the Field root when the rating has a label, description or error, else the box.

FAQ

Used in

More React input components