Rating
ratingCaptures a controlled rating with radio semantics, custom icons, and hover preview.
Usage
Basic usage
Uncontrolled default 3 stars, click/hover to change points; when controlled use value + onValueChange.
<Rating defaultValue={3} onValueChange={setValue} />Read only
readOnly Only displays ratings, no interaction.
<Rating value={4} readOnly />Dimensions
size controls the icon size (sm / md / lg).
<>
<Rating defaultValue={3} size="sm" />
<Rating defaultValue={3} size="md" />
<Rating defaultValue={3} size="lg" />
</>Custom color
color accepts token var() or any CSS color, hover is automatically derived.
<Rating defaultValue={4} color="var(--color-warning)" />Custom icon
icon accepts any icon, such as ❤️, and the empty state reuses the same shape.
<Rating
defaultValue={3}
color="var(--color-danger)"
icon={<Heart size="1em" fill="currentColor" />}
/>When to use
Use Rating to collect a star score or satisfaction level, or to show an existing score visually. Icons can be replaced with hearts, flames, or other symbols, while color-mix derives hover colors from the configured token. For a read-only view that only needs the numeric value, render text instead.
Import
import { Rating } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | number | — | Controlled current score. |
| defaultValue | number | — | Initial score when uncontrolled. |
| max | number | 5 | Maximum number of rating icons. |
| readOnly | boolean | false | Shows a noninteractive rating. |
| disabled | boolean | — | Disables interaction. |
| size | "sm" | "md" | "lg" | "md" | Icon size. |
| color | string | var(--color-primary) | Icon color as any CSS color or token variable; hover color is derived automatically. |
| className | string | — | Container class name |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: number | null) => void | Called when the user selects a rating. |
Slots
| Slot | Type | Description |
|---|---|---|
| icon | ReactNode | Custom icon, such as <Heart /> (default solid five-pointed star) |
| emptyIcon | ReactNode | Customize the empty status icon, reuse the icon by default (same shape and empty color) |
Example
const [v, setV] = useState<number | null>(3);
<Rating value={v ?? 0} onValueChange={setV} />Read-only and custom icon/color:
<Rating value={4} readOnly />
<Rating defaultValue={3} color="var(--color-danger)" icon={<Heart size="1em" fill="currentColor" />} />Usage guidelines
- The callback is
onValueChange, not the nativeonChange. - In
readOnlymode, no radio inputs are rendered; only a static graphic witharia-labelremains. Interactive mode uses real radio controls that can be selected by value. - Token colors must use the
--color-prefix, for examplevar(--color-primary). Barevar(--primary)is not resolved; see [[hulian-token-color-var-needs-color-prefix]]. - A custom
iconneedsfill="currentColor"to render as a solid shape, as shown above; otherwise only its stroke is colored.
Related
SecretField · Combobox · Listbox · Mentions · InputOTP · Upload
Playground
<Rating defaultValue={3} size="md" color="var(--color-primary)" />