# Rating input

> Whole or half-star ratings with hover previews, rolling values and native radio behaviour for keyboards, forms and screen readers.

A star rating is a form control, not five clickable SVGs. Native radios underneath provide real arrow-key navigation, validation and form submission while the visual layer adds whole or half-star fills, a lighter preview under the pointer, a fill that runs star to star in the direction the rating moved, a small throw on the star you pick and a rolling numeric readout. Selecting the same rating again can clear it, read-only and disabled states remain distinct, and every value stays an ordinary number or null.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/rating-input.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/rating-input
- Registry item (source): https://hairlineui.com/r/rating-input.json

## Usage

```tsx
import { RatingInput } from "@/components/rating-input";

<RatingInput
  label="Rate your experience"
  name="rating"
  value={rating}
  onValueChange={setRating}
  allowHalf
  required
/>
```

## A review form with a real rating value

The native radio group submits with the rest of the form. You can also keep the value in React for validation or a server action.

```tsx
"use client";

import * as React from "react";
import { RatingInput } from "@/components/rating-input";

export function ReviewForm() {
  const [rating, setRating] = React.useState<number | null>(null);

  async function submit() {
    if (rating === null) return;
    await fetch("/api/reviews", {
      method: "POST",
      body: JSON.stringify({ rating }),
    });
  }

  return (
    <RatingInput
      label="Overall rating"
      name="rating"
      value={rating}
      onValueChange={setRating}
      allowHalf
      required
      hint="Choose a rating from 0.5 to 5."
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | `number \| null` | – | The committed rating; null means no selection. |
| `onValueChange` | `(value: number \| null) => void` | – | Called for selection and clear-on-repeat. |
| `max` | `number` | `5` | Number of stars, clamped from 1 to 10. |
| `allowHalf` | `boolean` | `false` | Adds half-star values and independent left/right hit targets. |
| `clearable` | `boolean` | `true` | Clears when the current rating is selected again. |
| `labels` | `readonly string[]` | – | Words for whole rating levels; numeric text is the fallback. |
| `showValue` | `boolean` | `true` | Shows the rolling number and rating words. |
| `name` | `string` | – | Native radio group name used in form submission. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Star size: 24px, 29px or 34px. |
| `label / hint / error` | `ReactNode` | – | Shared field label, help and external error. |
| `required / disabled / readOnly` | `boolean` | – | Native validation and interaction states. |

## States

- **empty**: Quiet outlined stars and a Not rated label; the radio group has no selected value.
- **preview**: Hover or keyboard focus fills to the proposed rating at half strength and rolls the readout without committing it.
- **selected**: The fill runs star to star, 45ms apart, in the direction the rating moved; the picked star throws to 1.28× and settles.
- **half**: The left and right halves have separate hit areas and radio labels; the fill eases to 50%.
- **cleared**: Choosing the current value again empties the rating and returns the readout to Not rated.

## What it handles

Ratings often look simple but lose native keyboard behaviour, form values or half-star semantics once custom visuals are added. This keeps native radios under the entire interaction.

- **Native form behaviour**: Real named radio inputs submit the rating and participate in required-field validation.
- **Whole and half stars**: Half-star mode gives each side of a star its own labelled radio and precise 50% fill.
- **Preview before choosing**: Pointer and focus previews update the stars and readout without changing the committed form value.
- **Clear on repeat**: With clearable enabled, choosing the current rating again returns the value to null.
- **Directional readout**: The number rolls up or down with the preview while the words morph to the matching rating label.
- **Read-only and disabled**: Read-only preserves the submitted value without editing; disabled uses native disabled controls and reduced emphasis.

## Replaces

custom star buttons, react-rating, manual radio-group wiring, half-star hit targets, rating value and preview state

## Where it fits

- **Product reviews**: Collect a rating beside the review text and submit it with the form.
- **Feedback surveys**: Add a quick scored question with clear selected and empty states.
- **Marketplaces**: Rate sellers, stays or services with half-star precision.
- **Content and courses**: Let members rate a lesson, article or resource in place.

## Notes

- Each rating is a native radio labelled “n out of max”; Arrow keys move through values and Space selects.
- Pointer and focus previews do not call onValueChange. Escape or pointer leave restores the committed preview.
- Read-only radios remain in the form but are removed from the tab order; disabled radios use the native disabled attribute.
- Reduced motion removes star scaling, fill transitions and rolling numbers.

License: MIT (https://hairlineui.com/license#components)
