INPUT AND SELECTION

Star rating

Draft

An interactive rating control that lets users select a score by clicking or tapping star icons.

Usage

Common alternative names

Rating, review stars, score selector

---

Anatomy

Star rating comes in three variants depending on size and interactivity. Each variant uses a row of star icons within a container.

Container
(Required)

Star
(5 total required)

Interactive ratings

Interactive ratings consist of five large stars inside a container. Users tap or click a star to set their rating.

Container
(Required)

Star
(5 total required)

Descriptive ratings — medium

Medium descriptive ratings display a read-only score using medium-sized stars within a container.

Leading text
(Required)

Star icon
(Required)

Trailing text
(Optional)

4.5

(128)

Descriptive ratings — small

Small descriptive ratings display an inline text value, a single star icon, and optional trailing text such as a review count.

Usage guidelines coming soon.

Specs

Specs coming soon.

Content

Content guidelines coming soon.

Status & changelog

Status & changelog coming soon.

Code

---

Usage

Star Rating renders a row of star icons. Clicking a star selects that rating value. Hovering previews the potential selection.

import { StarRating } from '@arch-ui/components';

function Example() {
  const [rating, setRating] = React.useState(0);

  return (
    <StarRating
      value={rating}
      onChange={setRating}
      aria-label="Product rating"
    />
  );
}

Custom star count

<StarRating value={rating} onChange={setRating} numStars={10} />

---

Read-only display

Show a rating without allowing interaction.

<StarRating value={4.5} readOnly />

---

Half-star precision

<StarRating value={3.5} onChange={setRating} precision={0.5} />

---

Expected props

Prop	Type	Default	Description
value	number	0	The current rating value.
onChange	(value: number) => void	undefined	Called when the user selects a rating.
numStars	number	5	Total number of stars to display.
precision	0.5 | 1	1	Whether to allow half-star increments.
readOnly	boolean	false	Displays the rating without allowing interaction.
disabled	boolean	false	Disables the rating control.
size	'sm' | 'md' | 'lg'	'md'	Size of the star icons.

---

Accessibility

• Each star should be a radio button within a role="radiogroup" for proper screen reader support.
• Arrow keys should navigate between stars.
• The component should announce the selected value (e.g., "3 out of 5 stars").
• Read-only mode should use aria-readonly rather than aria-disabled.
• Always provide an aria-label describing what is being rated.

---

Best practices

Do:

• Use Star Rating for subjective feedback where a numeric scale is intuitive.
• Provide a visible label describing what is being rated.
• Show the numeric value alongside the stars for clarity.

Don't:

• Do not use Star Rating for precise numeric input -- use Slider or Input instead.
• Do not use more than 10 stars -- scales beyond 10 become hard to differentiate.
• Do not rely on colour alone to distinguish filled from empty stars.