---
name: rating-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Rating for
accessible rating capture or display using the Zag.js rating-group wrapper,
supported value/count/allowHalf/readOnly/displayOnly/disabled props, and token styling.
metadata:
component_version: "1.5.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/rating-group"
contributor_sources: "libs/ui/src/atoms/rating.tsx libs/ui/src/tokens/components/atoms/_rating.css libs/ui/stories/atoms/rating.stories.tsx libs/ui/src/atoms/rating.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Rating Usage
Use Rating for product reviews, satisfaction scores, read-only form values,
and explicit aggregate display. Do not build custom star maps.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Rating`.
**Use it when**
- Showing an average rating with count; collecting a rating in reviews or satisfaction surveys.
**Use something else when**
| Need | Use instead |
| --- | --- |
| A progress or score that isn't a rating | text or a meter |
**Do**
- Always show the numeric value and review count next to aggregate stars (`4.6 (128 reviews)`).
- Allow half values only in display, whole values in input unless the product needs halves.
- Label interactive ratings (`Rate this product`).
**Don't**
- Show stars with no reviews — show `No reviews yet`.
- Use colour-only stars without accessible text.
**Copy and states**
- Numbers formatted with the app locale (`4,6` in cs-CZ).
**Behaviour (from the UX spec)**
- Keep the average and the user's own vote apart: aggregates use `displayOnly`, a locked form score uses `readOnly`, never `disabled`.
- Hover only previews; a vote is set by click or keyboard and submitted by the form, never by hover or by showing the result.
- A missing score is not 0, and the review count is not the score.
**Figma → code**
| Figma | Code |
| --- | --- |
| `disabled=true` | `disabled` (input only) |
| `direction=vertical` / `horizontal` | not in code |
| no mode axis | interactive (default), `readOnly`, `displayOnly` |
| `allowHalf` | `allowHalf` (code default `true`) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Rating → UX guidelines*.
## Setup
```tsx
import { Rating } from "@techsio/ui-kit/atoms/rating"
```
Supported props:
```text
value/defaultValue: number
onChange: (value: number) => void
onHoverChange: (value: number) => void
count: number, default 5
allowHalf: boolean, default true
readOnly, displayOnly, disabled, name, labelText, translations, dir
size: sm | md | lg
```
## Core Patterns
### Accessible names and changing scales
Name editable ratings with `labelText`, `aria-label`, or `aria-labelledby` that
references mounted external text. These attributes name the actual radiogroup.
An external reference takes precedence; otherwise an explicit `aria-label`
overrides the visible-label reference. The unlabeled fallback is "Rating", but
use a meaningful question when collecting scores.
`count` is a positive integer (invalid/nonfinite counts fall back to a usable
scale). Scores clamp to `0..count`; editable values round to the nearest whole
or half star according to `allowHalf`. Read-only averages retain fractional
precision, with the final star's fill matching the fraction in either direction.
Uncontrolled initialization, runtime scale/precision changes and
native reset share this policy. Each actual editable uncontrolled correction
emits one `onChange`; reset emits none and restores the initial default under the **current**
constraints. Canceled resets do not change the score. Controlled invalid values
use a normalized display/submission projection without writing back to the
parent; application state remains the parent's responsibility.
If a focused star is removed, focus moves to a surviving star without changing
selection solely for focus recovery. Updates while focus is elsewhere never
steal focus. Zero scores retain one keyboard entry target without pretending a
star is selected.
### Feedback, targets and display semantics
Interactive stars have at least 32-pixel targets at every size, with outlined
empty stars, filled selected stars and a visible numeric value. `helpText` and
`validateStatus="default" | "error" | "warning" | "success"` provide associated
StatusText feedback; caller `aria-describedby` is merged onto the group and each
focus target, with `aria-invalid` and `aria-errormessage` for errors.
A `readOnly` form rating retains radiogroup/radio semantics, an inspectable
keyboard target and named form submission, while ignoring pointer/keyboard
mutation. It is not aggregate display. `displayOnly` instead exposes a
nonfocusable `role="img"` summary with no radios and no hidden form input.
Disabled takes priority over the read-only interaction state and removes all
keyboard targets. Sizes are `sm`, `md`,
`lg`, default `md`; stars are glyphs, not single-line boxed controls, so shared
form-control heights do not replace their square hit targets.
### Use controlled mode for editable rating state
```tsx
const [rating, setRating] = useState(0)
```
Zag exposes hover/value changes; the wrapper converts them to numbers.
### Separate read-only form values from aggregate display
```tsx
```
`readOnly` is an immutable **form control**, not an unavailable value: keep its
normal focus target and submission. `displayOnly` is an **aggregate summary**:
no tab stop, mutation callback or form submission, even if a name is passed.
It implicitly prevents editing and retains fractional averages. Name the image
meaningfully (for example "Average product rating: 4.6 out of 5") and show the
locale-formatted numeric average and review count in adjacent app copy.
Use `disabled` for a temporarily unavailable control, not for an average.
Native reset for a form rating follows the current form owner and waits for all
native/React cancellation before restoring an uncontrolled initial score under
the current constraints. Canceled reset preserves it and emits no reset change;
controlled state always belongs to the parent. A controlled reset requires an
explicit app-state update. Native nested-fieldset disabling and first-legend
exceptions apply; reset does not click a star or steal focus. Aggregate display
has no input and therefore no native form lifecycle.
### Use token-backed size and state styling
```tsx
```
The rating token file owns checked, highlighted, half, disabled, and readonly
visuals.
## Common Mistakes
### HIGH Custom star rendering
Wrong:
```tsx
{[1, 2, 3, 4, 5].map((i) => (
))}
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/rating.tsx
### HIGH Inline star colors
Wrong:
```tsx
```
Correct:
```tsx
```
Change `_rating.css` or app token overrides if the star colors need to change.
Source: libs/ui/src/tokens/components/atoms/_rating.css
### MEDIUM Missing label/name in forms
Wrong:
```tsx
```
Correct for form capture:
```tsx
```
Zag rating docs note `name` plus the hidden input for form usage.
Source: https://zagjs.com/components/react/rating-group
### MEDIUM Disabled used for read-only display
Wrong:
```tsx
```
Correct:
```tsx
```
## State consistency
An untouched rating displays `0 / count` with no checked radio. A checked half-star option announces its exact value (for example, “4.5 stars”); the visible score is also associated with the group and each interactive focus target. `translations.ratingValueText` receives the exact selected value. Disabled stars and their label use disabled foregrounds. Long scales wrap inside the available width without shrinking the minimum 32px targets.
## Validation Commands
```sh
rg -n "map\\(.*\\*|text-yellow|]*className=.*(text-|fill-|stroke-)" apps
rg -P -n "]*(name=|readOnly|labelText=))" apps
rg -n "]*disabled" apps
rg -n "onHoverChange|allowHalf|count=" apps
```
## Silent native form reset
Native reset calls no value-change callbacks and dispatches no native `input`
or `change` events, in controlled or uncontrolled usage. Uncontrolled controls
silently restore their default; controlled controls
keep the latest parent value and re-sync visible/accessibility/native submission
state to it. Handle the form's `onReset` to intentionally change parent state.
Canceled resets leave every channel unchanged. Reset does not synthesize events
or move focus; the first real user edit afterward emits exactly one normal
callback, including when the same value was entered before reset.
Expose the disabled state across the whole widget so assistive tech and contrast checks treat it as inactive.