KQ-1515 · STAR/PEEK

Star Peek

A star rating that shows what you are about to say: hovering, scrubbing or arrowing fills the stars toward the pointer on springs.flick — a star can stand a third full — while a soft ghost reaches ahead to the value a press would commit, stepping on springs.snap, and a short phrase for that score peeks up from behind the question and glides sideways on springs.snap to sit over the ghost's edge. Committing settles the fill and pops the filled stars in sequence, each kicked on springs.recoil a cascade apart, with a chime as the last lands. It is a radiogroup with one radio per half star: arrows move and preview, Home and End jump, Enter and Space commit, Escape ends the preview.

KQ-1515 · STAR/PEEK

Basinworks Lodge · Room 12

How was your stay?

not rated · hover or arrow to preview

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/star-peek

Props

value / defaultValue: number; default — / 0; The rating, controlled or uncontrolled; 0 is unrated. Snapped to the step.
onValueChange: (value: number) => void; default —; Fires from the press, tap, drag or key that committed a rating.
onPreviewChange: (value: number | null) => void; default —; Fires as a preview starts, moves to another step, and ends (null).
count: number; default 5; How many stars, 1 to 10.
half: boolean; default true; Half-star steps: two radios per star.
phrases: "warm" | "plain" | "off" | string[]; default "warm"; The phrase that peeks above a previewed score: a built-in set, off, or your own — one per star, one per half step, or any length mapped across the scale.
label: string; default "Your rating"; The question over the stars, and the radio group's name.
hideLabel: boolean; default false; Keep the question for assistive technology only; its row stays, for the phrase to peek into.
showValue: boolean; default true; Show the number (and "/ count" where there is room) beside the stars, with the widest value's width reserved.
format: (value: number, count: number) => string; default "4.5", "4", "–"; How a value is written beside the stars and spoken in each radio's name.
commitOnArrow: boolean; default false; Arrow keys select as they move, as a plain radio group does, instead of previewing until Enter or Space.
color: "amber" | "rose" | "cobalt" | "mint" | string; default "amber"; The stars' colour: a named pigment that reads the same in both themes, or any CSS colour.
size: "sm" | "md" | "lg"; default "md"; Stars 24, 32 or 40px; they shrink to fit a narrow row.
name: string; default —; Form field name: the rating is submitted in a hidden input.
readOnly: boolean; default false; Shows the rating with no preview or commit; still focusable and announced.
sound: boolean; default false; A tick per previewed step, rising with the value, and a chime on commit; only in answer to the visitor.
disabled: boolean; default false; Disables and dims the rating; nothing in it can be focused.
className: string; default —; Classes for the root column.

Prop	Type	Default	Description
value / defaultValue	number	— / 0	The rating, controlled or uncontrolled; 0 is unrated. Snapped to the step.
onValueChange	(value: number) => void	—	Fires from the press, tap, drag or key that committed a rating.
onPreviewChange	(value: number \| null) => void	—	Fires as a preview starts, moves to another step, and ends (null).
count	number	5	How many stars, 1 to 10.
half	boolean	true	Half-star steps: two radios per star.
phrases	"warm" \| "plain" \| "off" \| string[]	"warm"	The phrase that peeks above a previewed score: a built-in set, off, or your own — one per star, one per half step, or any length mapped across the scale.
label	string	"Your rating"	The question over the stars, and the radio group's name.
hideLabel	boolean	false	Keep the question for assistive technology only; its row stays, for the phrase to peek into.
showValue	boolean	true	Show the number (and "/ count" where there is room) beside the stars, with the widest value's width reserved.
format	(value: number, count: number) => string	"4.5", "4", "–"	How a value is written beside the stars and spoken in each radio's name.
commitOnArrow	boolean	false	Arrow keys select as they move, as a plain radio group does, instead of previewing until Enter or Space.
color	"amber" \| "rose" \| "cobalt" \| "mint" \| string	"amber"	The stars' colour: a named pigment that reads the same in both themes, or any CSS colour.
size	"sm" \| "md" \| "lg"	"md"	Stars 24, 32 or 40px; they shrink to fit a narrow row.
name	string	—	Form field name: the rating is submitted in a hidden input.
readOnly	boolean	false	Shows the rating with no preview or commit; still focusable and announced.
sound	boolean	false	A tick per previewed step, rising with the value, and a chime on commit; only in answer to the visitor.
disabled	boolean	false	Disables and dims the rating; nothing in it can be focused.
className	string	—	Classes for the root column.