# Rating input (goodtabs UI)

Five stars as a radio group, with hover preview, arrow keys and a read only display.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/rating-input.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/rating-input`

## Usage

```tsx
import { RatingInput } from "@/components/ui/rating-input"

<RatingInput value={rating} onValueChange={setRating} />
<RatingInput readOnly value={4} size="sm" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number` |  | Controlled value, 0 to max. Leave out to go uncontrolled. |
| defaultValue | `number` | `0` | Starting value for the uncontrolled form. |
| onValueChange | `(value: number) => void` |  | Fires with the new value. |
| max | `number` | `5` | Number of stars. |
| size | `"sm" | "default" | "lg"` | `"default"` | Star size: 14, 16 or 24px. |
| readOnly | `boolean` | `false` | Renders a static display with an aria-label like Rated 4 of 5. |
| label | `string` | `"Rating"` | Accessible name of the group. |

## When to use

- Collecting a one to five score in a review or feedback form
- Showing a score next to a product, a review or a listing with readOnly
- When the input should stay small enough to sit on one row with a label

## When not to use

- Scales with more than seven steps or with text anchors: use a slider or a radio group
- A like or save mark, which is one toggle, not a scale
- Scores that need half stars; this one steps by whole numbers

## Notes for agents

- onValueChange is a function, so the component that renders a controlled RatingInput must be a client component
- Roving tabindex: one star is in the tab order, arrow keys move the value and the focus, Home and End jump
- A value of 0 means nothing chosen; the first star is then the tab stop
- readOnly swaps the buttons for a role img with the label Rated n of max, so it is one accessible node
- No colour: filled stars use fill-current on text-foreground, empty ones are the muted outline

Docs: https://ui.goodtabs.co/components/rating-input