# 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`                  | —       | No       | Current rating value                        |
| `defaultValue` | `number`                  | `0`     | No       | Uncontrolled initial value                  |
| `onChange`     | `(value: number) => void` | —       | No       | Change handler                              |
| `max`          | `number`                  | `5`     | No       | Maximum rating                              |
| `readonly`     | `boolean`                 | `false` | No       | Disables interaction, shows read-only stars |
| `size`         | `'sm' \| 'md' \| 'lg'`    | `'md'`  | No       | Star size                                   |
| `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.