# Rating

```tsx
import { Rating } from '@tangible/ui';
```

Interactive docs and examples: [Rating in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-rating--docs).

## Rating props

| Prop | Type | Default | Description |
| - | - | - | - |
| `allowClear?` | `boolean` | | Allow clicking the current selection to clear back to 0 |
| `aria-label?` | `string` | | Accessible label for the rating group. Defaults to "Rating: X of Y" |
| `className?` | `string` | | |
| `defaultValue?` | `number` | `0` | Uncontrolled initial value |
| `disabled?` | `boolean` | | Disable interaction (keeps semantics) |
| `gap?` | `string` | | Gap override (e.g. '0.25rem') – otherwise uses density utilities |
| `labels?` | `RatingLabels` | | Override default English strings for i18n. |
| `max?` | `number` | `5` | Maximum icons shown |
| `name?` | `string` | | Name for the radio group (if you care about form posts) |
| `onValueChange?` | `(value: number) => void` | | Called when the value changes |
| `readOnly?` | `boolean` | | Presentational readOnly (no form semantics) |
| `size?` | `"lg" \| "md" \| "sm"` | `'lg'` | Size maps to icon + spacing |
| `theme?` | `"danger" \| "primary" \| "secondary" \| "success" \| "warning"` | `'secondary'` | Theme feeds foreground color tokens |
| `value?` | `number` | | Controlled value (1..max). Use with onValueChange |

## Examples

- [Disabled](https://storybook-tangible-ui.pages.dev/?path=/story/primitives-rating--disabled): Disabled keeps the radio semantics (the value still reads out and posts with forms) but blocks interaction — unlike `readOnly`, which drops form semantics entirely.

- [Allow Clear](https://storybook-tangible-ui.pages.dev/?path=/story/primitives-rating--allow-clear): With `allowClear`, clicking the currently selected star clears the rating back to 0. Set `allowClear={false}` for required ratings.

- [Unrated](https://storybook-tangible-ui.pages.dev/?path=/story/primitives-rating--unrated): The zero state — no star selected. This is what users see before rating, and what `allowClear` returns to.

- [Accessibility](https://storybook-tangible-ui.pages.dev/?path=/story/primitives-rating--accessibility): All announced strings route through `labels`. The interactive radiogroup label (`labels.group`) must **not** encode the current value — each focused radio announces its own state, so a value-bearing group label double-announces. Read-only mode is a single `img` whose label (`labels.rating`) *does* carry the value, since nothing else announces it.

Other stories: Basic, Sizes, Themed, Controlled, Read Only, Custom Max ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-rating--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-rating-active`
- `--tui-rating-inactive`
- `--tui-rating-scale`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-rating--docs