Adv UI

Rating

A row of stars, or any icon, to give a score with a press or the keyboard, or to show one read-only, with half and part-filled icons.
Stable
Web
iOS
Android
@advui/core
Source
JSX
<Rating aria-label="Playground rating" defaultValue={3} />
PropsOpen in Playground
size

Installation

pnpm
pnpm add @advui/core
npm
npm install @advui/core

Usage

import { Field, Rating } from '@advui/core'

<Field label="How was your stay?">
  <Rating value={stars} onValueChange={setStars} allowHalf />
</Field>

<Rating aria-label="Average rating" readOnly value={4.3} size="sm" />

Examples

Basic

A controlled rating with a word for each score beside it.
Good

Half ratings and sizes

With `allowHalf`, each half of an icon is its own value. Small, medium and large.

Read-only score

A product’s average beside its review count; 4.3 fills part of the fifth star.
4.3(1,248 reviews)

In a Field

The field names the rating, shows the error until one is picked, and submits it as `stay`.
Your rating is shown with your review.Pick a rating.

Other icons and counts

Hearts in the primary color, and a ten-point scale.

API reference

Rating

A row of icons in a View; style props go to the row.
PropTypeDefaultDescription
valuenumber—The rating, from 0 (none) to `count`, when you control it.
defaultValuenumber0Starting `value` when uncontrolled.
onValueChange(value: number) => void—Called when the user picks a rating with a press, a key or a swipe.
countnumber5How many icons, and the highest rating.
allowHalfbooleanfalseLets the user pick half ratings (3.5): the start half of an icon picks the half, the end half the whole. Keys step by 0.5.
readOnlybooleanfalseShows the rating without letting anyone change it, as an image named by its value. Any fraction shows as a part-filled icon: 4.3 fills 30% of the fifth.
size'sm' | 'md' | 'lg''md'Icons of 16, 24 or 32px.
iconIconComponentStarIconThe icon to repeat: any icon from `@advui/icons` (`HeartIcon`), one made with `createIcon`, or a Lucide icon. It must take `fill`.
colorColorTokens'warning', outlined in 'warningSoftForeground'Fill and outline of the chosen icons. The default amber has a darker outline so the icons stand out on light backgrounds.
emptyColorColorTokens'mutedForeground'Outline of the icons that are not chosen. `error` while invalid.
getValueText(value: number) => string"3 of 5"The value screen readers read, and a read-only rating’s name. Translate it here.
disabledbooleanfalseDims the icons and ignores presses and keys. Also on inside a disabled Field or Form.
invalidbooleanfalseError outline on the empty icons and `aria-invalid`. On inside a Field with an `error`.
namestring—Field name for a native form: the rating submits its value under it.Web only.
aria-labelstring—Names the rating. Inside a Field, the field’s label names it instead. A read-only rating reads it before the value.

Accessibility

  • An interactive rating is one role="slider" from 0 to count, as in the WAI-ARIA rating slider example, with aria-valuetext such as "3 of 5" (getValueText). The icons inside are hidden from assistive technology.
  • Named by aria-label or, inside a Field, by the field’s label (aria-labelledby); the field’s help and error text describe it. A slider has no required state, so say what is required in the help or error text.
  • readOnly makes it role="img", named by its label and value ("Average rating: 4.3 of 5"), and takes it out of the Tab order.
  • The chosen icons are filled, not only colored, so the score does not rely on color alone. The default empty outline (mutedForeground) has at least 3:1 contrast on the background in every preset.
  • On iOS and Android each icon reaches a 44pt touch target with hitSlop.
Keyboard interactions
KeyAction
ArrowRight / ArrowUpOne step higher (half a step with `allowHalf`).
ArrowLeft / ArrowDownOne step lower. Left and right swap in RTL.
HomeClears the rating (0).
EndPicks the top score.

Platform notes

Web
A div with role="slider" and tabindex="0". Hovering an icon previews its value until the pointer leaves. With name, a hidden input submits the value.
iOS
An adjustable element: VoiceOver users swipe up or down to change it, and hear the value text. Tap an icon (or its half) to pick it.
Android
An adjustable element: TalkBack users change it with its swipe adjustments, and hear the value text. Tap an icon (or its half) to pick it.

Related components

Slider
Radio Group
Field
Toggle Group
Since v0.14.0Last updated Nov 2, 2026Edit this page on GitHub
PreviousRadio Group
NextSelect