Rating

A star rating input with sweeping fills, optional half stars, a rolling word label and a read-only display mode.

When to use

• Capturing a quick opinion: viewing feedback, draft quality, satisfaction.
• Showing an average score with readOnly (and allowHalf for 4.5-style values).
• For numeric precision use NumberField or Slider; for thumbs up/down feedback use a pair of buttons.

Usage

import { Rating } from "@/components/iris/rating/rating";
function ViewingFeedback() {
  const [stars, setStars] = React.useState(0);
  return h(Rating, { label: "How was the viewing", value: stars, onChange: setStars, name: "rating" });
}

Props

Prop	Type	Default	Description
label	string	required	Visible label and accessible name for the group.
value / defaultValue	number	– / 0	Controlled or initial value; 0 means not rated.
onChange	(value: number) => void	–	Called with the committed value; 0 means cleared.
max	number	5	Number of stars.
allowHalf	boolean	false	Pointer, touch and arrow keys move in half stars.
allowClear	boolean	true	Choosing the current value again clears it; Backspace/Delete also clear.
readOnly	boolean	false	Static display (role="img") such as an average.
disabled	boolean	false	Turns off interaction and dims the stars.
size	"sm" | "md" | "lg"	"md"	Star size.
showValue	boolean	true	Word or number for the previewed value beside the stars.
valueLabels	readonly string[]	Poor…Excellent for 5 whole stars	One word per whole star; otherwise "4 out of 5".
emptyLabel	string	"Not rated"	Shown when the value is 0.
description / name / className	string	–	Hint under the stars, hidden form input name, root class.

Notes

• Interactive mode is a radiogroup of role="radio" buttons with a single tab stop; arrows step, Home/End jump, number keys pick directly, and commits are announced politely.
• Hover previews a value, touch and drag scrub across stars; the fill sweeps in order and committed stars pop. Reduced motion makes all of it instant.
• Filled stars use the orange token (the committed value shows as a faint orange underneath a hover preview); empty stars are a line-strong outline that softens to a line solid once a value shows, so check contrast where ratings carry meaning.