Loading…

Rating

beta

A star rating input with half stars, a springy hover preview and a burst on the chosen star — or a read-only display of any fraction.

Forms
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add rating

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

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

Examples

Every example the tests run, live and operable, side by side.

Default
Half Stars
Read Only
Sizes
Custom Icon
Controlled
Disabled

API

Generated from the component's own types, so a prop cannot appear here without existing.

<Rating>

Prop	Type	Default
`allowHalf` Lets each star be chosen by half, by where the pointer sits inside it.	`boolean`	`false`
`defaultValue` Initial value when uncontrolled. Default 0.	`number`	`0`
`disabled`	`boolean`	`false`
`getLabel` Accessible name of each option. Default "1 star", "2.5 stars".	`(value: number, max: number) => string`	`defaultGetLabel`
`icon` A glyph to use instead of the star, drawn as an outline and a solid fill.	`ReactNode`	—
`max` How many stars. Default 5.	`number`	`5`
`name` Submits the value with a form under this name.	`string`	—
`onValueChange` Called when a star (or half star) is chosen by pointer or keyboard.	`(value: number) => void`	—
`readOnly` Shows the value as an image named "3.5 out of 5"; nothing can be chosen.	`boolean`	`false`
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`value` Controlled value; 0 is no rating.	`number`	—

Plus every attribute of <div> except defaultValue, onChange, children.

Accessibility

A radiogroup (named "Rating" unless given aria-label or aria-labelledby) of role="radio" buttons, one per star or per half star, each named by getLabel ("3.5 stars"). One tab stop on the chosen option; Right/Down and Left/Up move and select (Left/Right mirror in right-to-left layouts), wrapping at the ends like native radios, with Home/End; Space or Enter selects the focused option. Focus previews the value and rings the whole star. Filled stars are solid and empty ones outlined, so the value never rests on colour alone. readOnly renders a role="img" named "3.5 out of 5". Glyphs, the preview pop and the burst are aria-hidden and stop under reduced motion. Half-star hit zones at size sm are narrow; prefer md or lg for touch.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

allowHalf

Lets each star be chosen by half, by where the pointer sits inside it.

boolean

false

defaultValue

Initial value when uncontrolled. Default 0.

number

0

disabled

boolean

false

getLabel

Accessible name of each option. Default "1 star", "2.5 stars".

(value: number, max: number) => string

defaultGetLabel

icon

A glyph to use instead of the star, drawn as an outline and a solid fill.

ReactNode

—

max

How many stars. Default 5.

number

5

name

Submits the value with a form under this name.

string

—

onValueChange

Called when a star (or half star) is chosen by pointer or keyboard.

(value: number) => void

—

readOnly

Shows the value as an image named "3.5 out of 5"; nothing can be chosen.

boolean

false

size

"sm" | "md" | "lg"

"md"

value

Controlled value; 0 is no rating.

number

—