# Rating

## Overview

A star-based rating input that allows users to rate items on a 1–5 (or custom range) scale. Supports both interactive rating input and read-only display modes.

---

## When to Use

- Product or service reviews
- Satisfaction ratings in feedback forms
- Read-only quality scores in lists and tables

---

## Props

| Prop           | Type                                      | Default | Required | Description                                                  |
| -------------- | ------------------------------------------ | ------- | -------- | -------------------------------------------------------------- |
| `value`        | `number`                                   | `0`     | No       | Current rating value                                            |
| `onChange`     | `(value: number) => void`                  | —       | No       | Change handler                                                  |
| `max`          | `number`                                   | `5`     | No       | Maximum rating                                                  |
| `readonly`     | `boolean`                                  | `false` | No       | Prevents interaction but keeps visible (no greyed-out styling) |
| `disabled`     | `boolean`                                  | `false` | No       | Disables interaction and applies `opacity-50` styling          |
| `size`         | `'sm' \| 'md' \| 'lg'`                     | `'md'`  | No       | Star size                                                       |
| `showValue`    | `boolean`                                  | `false` | No       | Shows the numeric value next to the stars                      |
| `allowHalf`    | `boolean`                                  | `false` | No       | Enables half-star precision (0.5 increments)                   |
| `getAriaLabel` | `(value: number, max: number) => string`   | —       | No       | Custom aria-label generator, receives the star value and max   |
| `className`    | `string`                                   | —       | No       | Additional CSS classes                                          |

---

## Examples

### Interactive Rating

```tsx
import { Rating } from 'xertica-ui/ui';
import { useState } from 'react';

const [rating, setRating] = useState(0);

<div className="space-y-2">
  <Rating value={rating} onChange={setRating} />
  <p className="text-sm text-muted-foreground">{rating} out of 5 stars</p>
</div>;
```

### Read-Only (in a card or table)

```tsx
<Rating value={4.5} readonly size="sm" />
```

### In a Form

```tsx
<FormField
  control={form.control}
  name="rating"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Your Rating</FormLabel>
      <FormControl>
        <Rating value={field.value} onChange={field.onChange} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- Use `readonly` (lowercase) for display-only contexts — never add `pointer-events-none` manually.
- Do not use `{...field}` spread — use `value={field.value}` and `onChange={field.onChange}`.
- For half-star display values (e.g., `4.5`), only use in `readonly` mode.