Rating inputNew
Whole or half-star ratings with hover previews, rolling values and native radio behaviour for keyboards, forms and screen readers.
Used forProduct reviewsFeedback surveysMarketplacesContent and courses
Install with the shadcn CLI
Registered the namespace? Then it’s shadcn add @hairline/rating-input. Set it up
Templates
Need the whole page?
61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.
Where it’s used
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.
What it handles for you
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.
Overview
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.
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.
Usage
Works with
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.
Props
- value / defaultValue
- number | null
- The committed rating; null means no selection.
- onValueChange
- (value: number | null) => void
- Called for selection and clear-on-repeat.
- max= 5
- number
- Number of stars, clamped from 1 to 10.
- allowHalf= false
- boolean
- Adds half-star values and independent left/right hit targets.
- clearable= true
- boolean
- Clears when the current rating is selected again.
- labels
- readonly string[]
- Words for whole rating levels; numeric text is the fallback.
- showValue= true
- boolean
- Shows the rolling number and rating words.
- name
- string
- Native radio group name used in form submission.
- size= "md"
- "sm" | "md" | "lg"
- 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.
Accessibility and motion
- 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.
Requirements
React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.
The CLI also installs Number roll, Text morph.
Source
Registry item: /r/rating-input.json


