> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Rate

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Lets people choose a rating with full or half steps.

## When to use

Use for a short ordered scale. Add a visible label and explain what the highest and lowest ratings mean.

## Examples


### Controlled half-star rating
Arrow keys move the rating. allowHalf enables half steps and tooltips explain each whole-star score.
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Rate, Stack } from '@rockshin/tao-ui';

export default function Example() {
  const [value, setValue] = useState(3.5);
  return (
    <Stack gap="sm">
      <span>How was your experience?</span>
      <Rate
        value={value}
        onChange={setValue}
        allowHalf
        aria-label="Experience rating"
        tooltips={['Poor', 'Fair', 'Good', 'Very good', 'Excellent']}
      />
      <output>{value} / 5</output>
    </Stack>
  );
}
```

### Allow or prevent clearing
With allowClear enabled, clicking the selected score again resets it to zero.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';

export default function Example() {
  return (
    <Stack gap="md">
      <div>
        <p>Click the selected star to clear</p>
        <Rate defaultValue={3} aria-label="Clearable rating" />
      </div>
      <div>
        <p>A value is always retained</p>
        <Rate
          defaultValue={3}
          allowClear={false}
          aria-label="Required rating"
        />
      </div>
    </Stack>
  );
}
```

### Read-only and disabled
readOnly presents an existing score; disabled communicates that the control is unavailable.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';

export default function Example() {
  return (
    <Stack gap="md">
      <div>
        <p>Average: 4.5</p>
        <Rate value={4.5} allowHalf readOnly aria-label="Average rating" />
      </div>
      <div>
        <p>Rating unavailable</p>
        <Rate defaultValue={3} disabled aria-label="Unavailable rating" />
      </div>
    </Stack>
  );
}
```

### Custom characters and count
character can be a node or a function of the item index.
```tsx preview
import { Rate, Stack } from '@rockshin/tao-ui';

export default function Example() {
  return (
    <Stack gap="md">
      <Rate
        count={3}
        defaultValue={2}
        character="♥"
        aria-label="Three-heart rating"
      />
      <Rate
        count={5}
        defaultValue={3}
        character={({ index }) => (
          <span style={{ fontSize: 18 }}>{(index ?? 0) + 1}</span>
        )}
        aria-label="Numeric rating"
      />
    </Stack>
  );
}
```

### Sizes and provider defaults
small, middle and large are accepted. The native medium spelling is also supported.
```tsx preview
import { Rate, Stack, TaoProvider } from '@rockshin/tao-ui';

export default function Example() {
  return (
    <TaoProvider size="small">
      <Stack gap="md">
        <Rate defaultValue={3} aria-label="Inherited small rating" />
        <Rate defaultValue={3} size="middle" aria-label="Medium rating" />
        <Rate defaultValue={3} size="large" aria-label="Large rating" />
      </Stack>
    </TaoProvider>
  );
}
```

### Focus and semantic customization
Use the ref when another action needs to move focus into the rating control.
```tsx preview
import { useRef } from 'react';
import { Button, Rate, Stack } from '@rockshin/tao-ui';
import type { RateRef } from '@rockshin/tao-ui';

export default function Example() {
  const ref = useRef<RateRef>(null);
  return (
    <Stack gap="md">
      <Button variant="secondary" onClick={() => ref.current?.focus()}>
        Focus rating
      </Button>
      <Rate
        ref={ref}
        defaultValue={4}
        aria-label="Custom rating"
        styles={{
          root: { color: 'var(--tao-primary)' },
          item: { marginInlineEnd: 8 },
        }}
      />
    </Stack>
  );
}
```

## API


### [#](#rate)Rate



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |

