Koala UI

Rating

Pro

A 1-to-N star rating built on Radix RadioGroup: roving focus, arrow keys and hover preview for free. Active stars render solid, the one place the DS opts out of its outline-only rule, and half stars read cleanly.

4 of 5

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add rating

Usage#

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Get the code

Have a license? Unlock it here

Sizes#

sm (16px), md (20px), and lg (28px) line up with the rest of the control scale.

sm
md
lg

Tones#

tone recolors the active glyph, independent of the icon: amber (default) is the vivid review-gold for stars, and red is the love-red that suits a Heart. Both ride dedicated rating tokens, brighter than the warning status hue.

amber
red

Variants#

filled (default) is the classic solid-star look: the active glyph renders at the fill weight, the rest stay outline. outline keeps the DS rule, drawing the active star as a tinted outline instead.

outline
filled

Read-only & fractional#

readOnly renders a static display and accepts fractional values: an average like 4.3 shows a partly-filled star via the clip overlay.

5.0
4.3
2.5

Custom icon & length#

Swap the star for any Koala icon with icon, and set the scale length with max. Recolor the fill with tone: amber (default review-gold) or red, which suits a heart. The icon follows the active variant: solid by default, outline with variant="outline".

Disabled#

API reference#

Rating

Interactive, it wraps Radix RadioGroup.Root with one RadioGroup.Item per star; with readOnly it renders a static <div role="img">. Forwards native <div> props (except onChange, defaultValue and dir) and accepts className, merged last.

PropTypeDefaultDescription
valuenumber-Controlled value. Whole numbers when interactive; fractional values (e.g. 4.3) render when readOnly.
defaultValuenumber0Uncontrolled initial value.
onValueChange(value: number) => void-Called with the new whole-star value when a star is selected.
maxnumber5Number of stars in the scale.
readOnlybooleanfalseDrops the RadioGroup for a static, fraction-capable display, labelled like "Rating: 4.3 of 5".
disabledbooleanfalseDisables every star and fades the row.
namestring-Form field name, passed to the underlying RadioGroup so the value submits with a form.
iconIconStarAny Koala icon component to use instead of the star (e.g. Heart). It follows variant: solid by default, outline with variant="outline".
aria-labelstring"Rating"Names the group and builds each star's label, e.g. "Rating 3 of 5".
size"sm" | "md" | "lg""md"Star size: 16px, 20px or 28px.
variant"filled" | "outline""filled"filled draws the active glyph at the fill weight; outline keeps it a tinted outline.
tone"amber" | "red""amber"Hue of the active glyph: review-gold, or the love-red that suits a heart.
Data attributeDescription
data-disabledSet by Radix on the group and each star when disabled.
data-stateOn each star: "checked" for the selected star, "unchecked" otherwise (interactive only).

FAQ#

Set `readOnly` and pass the fractional `value`. Read-only mode drops the RadioGroup for a static display and clips a colored glyph over an empty one, so a partly-filled star reads cleanly. Interactive ratings only commit whole numbers.