> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/rate.html

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

# Rate

Select or display a rating.


## Basic usage

Click the selected rating again to clear it to `0`, or set `allowClear={false}` to prevent clearing. Hover previews a rating; leaving restores the selection.


Project rating

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/rate/basic.tsx"
import { FormField, Rate } from '@ifhover/leaf-ui';

export function RateBasic() {
  return (
    <FormField label="Project rating" layout="vertical">
      <Rate defaultValue={3} />
    </FormField>
  );
}
```

Expand code


## Examples

### Half-star ratings

Enable `allowHalf` to select in increments of `0.5`. `value` and `onChange` use the corresponding decimal values.


Project rating

half.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/rate/half.tsx"
import { FormField, Rate } from '@ifhover/leaf-ui';

export function RateHalf() {
  return (
    <FormField label="Project rating" layout="vertical">
      <Rate defaultValue={3.5} allowHalf />
    </FormField>
  );
}
```

Expand code

### Read only and disabled

Both prevent changes. Use `readOnly` when the value must still be included in form submission.


Read onlyDisabled

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/rate/states.tsx"
import { Flex, Grid, Rate, Text } from '@ifhover/leaf-ui';

export function RateStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">Read only</Text>
      <Flex align="center" wrap>
        <Rate aria-label="Read-only rating" defaultValue={3} readOnly />
      </Flex>
      <Text tone="muted">Disabled</Text>
      <Flex align="center" wrap>
        <Rate aria-label="Disabled rating" defaultValue={3} disabled />
      </Flex>
    </Grid>
  );
}
```

Expand code

[](#)
### Controlled rating

Manage the rating with `value` and `onChange`. Reset application state when the form resets; controlled fields do not restore themselves.


Project rating

Current rating: 3Reset

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/rate/controlled.tsx"
import { Button, FormField, Rate, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function RateControlled() {
  const [value, setValue] = useState(3);

  return (
    <Space direction="vertical" align="start">
      <FormField label="Project rating" layout="vertical">
        <Rate value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        Current rating: {value}
      </Text>
      <Button variant="outline" onClick={() => setValue(3)}>
        Reset
      </Button>
    </Space>
  );
}
```

Expand code

### Rating colors

`colorByValue` changes the color with the score. Set `color` for a fixed color, which takes precedence over score-based colors.


By scoreFixed color

colors.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/rate/colors.tsx"
import { Flex, Grid, Rate, Text } from '@ifhover/leaf-ui';

export function RateColors() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">By score</Text>
      <Flex align="center" wrap>
        <Rate aria-label="Score-based colors" defaultValue={2} colorByValue />
      </Flex>
      <Text tone="muted">Fixed color</Text>
      <Flex align="center" wrap>
        <Rate aria-label="Fixed color" defaultValue={2} color="#1d9bf0" />
      </Flex>
    </Grid>
  );
}
```

Expand code

#### Forms and keyboard

Use `FormField` for a label and `name` to include the value in FormData. Clearing submits an empty string. Uncontrolled ratings support form reset; set `required` to require a nonzero rating. See [Form](https://ifhover.github.io/leaf-ui/en/components/form.md) for form integration.

Arrow keys adjust the rating, Home / End go to the ends, and Delete / Backspace clear when clearing is allowed.


## API

### Rate API

Configure the rating value, precision, read-only state and clearing behavior.

| Property       | Type                                | Default                             | Description                                                                        |
| -------------- | ----------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| `value`        | `number`                            | —                                   | Controlled rating.                                                                 |
| `defaultValue` | `number`                            | `0`                                 | Initial rating for uncontrolled usage.                                             |
| `onChange`     | `(value: number) => void`           | —                                   | Return the new rating, or 0 when cleared.                                          |
| `count`        | `number`                            | `5`                                 | Number of stars, up to 20                                                          |
| `allowHalf`    | `boolean`                           | `false`                             | Allow half-star ratings.                                                           |
| `allowClear`   | `boolean`                           | `true`                              | Clear to 0 when the current rating is selected again.                              |
| `disabled`     | `boolean`                           | `false`                             | Disable interaction.                                                               |
| `readOnly`     | `boolean`                           | `false`                             | Prevent rating changes while retaining form submission.                            |
| `size`         | `'sm' \| 'md' \| 'lg'`              | `'md'`                              | Star size                                                                          |
| `color`        | `string`                            | —                                   | Fixed rating color, taking precedence over colorByValue; gold when neither is set. |
| `colorByValue` | `boolean`                           | `false`                             | Use low, medium and high score colors                                              |
| `colors`       | `readonly [string, string, string]` | `['#ef5350', '#f49b23', '#ffc53d']` | Low, medium and high colors, with thresholds of 40% and 70%                        |
| `name`         | `string`                            | —                                   | Field name in native FormData.                                                     |
| `form`         | `string`                            | —                                   | ID of the associated native form.                                                  |
| `required`     | `boolean`                           | `false`                             | Require a non-zero rating.                                                         |
