# Rating

> Source: https://design.nanatec.co.ke/components/rating/
> A rating component for displaying and collecting star (or heart/dot) ratings. Supports fractional display, half- and full-step input, multiple symbols, read-only and disabled states, sizes, hover preview, keyboard control and an optional value label.

A rating component for displaying and collecting star (or heart/dot) ratings. Supports fractional display, half- and full-step input, multiple symbols, read-only and disabled states, sizes, hover preview, keyboard control and an optional value label.

## Preview

```html
<nana-rating value="3"></nana-rating>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/rating";
```

## Basic usage

```html
<nana-rating value="3"></nana-rating>
```

## Sizes

```html
<nana-rating size="sm" value="3"></nana-rating>
<nana-rating size="md" value="3"></nana-rating>
<nana-rating size="lg" value="3"></nana-rating>
```

## Precision & states

`precision="half"` enables half-stars; `show-value` shows the number;
`readonly` / `disabled` make it non-interactive.

```html
<nana-rating value="3.5" precision="half" show-value></nana-rating>
<nana-rating value="4.5" precision="half" readonly show-value></nana-rating>
<nana-rating value="2" disabled></nana-rating>
<nana-rating value="6" max="10" show-value></nana-rating>
```

## Icon variants

The `variant` attribute sets the symbol — `star` (default), `heart`, or `circle`.

```html
<nana-rating value="3" variant="star"></nana-rating>
<nana-rating value="3" variant="heart"></nana-rating>
<nana-rating value="3" variant="circle"></nana-rating>
```

## API

## Events

| Event | Type | Description |
|---|---|---|
| `nana-change` | `CustomEvent` | Fired when the value is committed (`detail.value`) |
| `nana-input` | `CustomEvent` | Fired while hovering over a new value (`detail.value`) |

## CSS Variables

| Variable | Default | Description |
|---|---|---|
| `--nana-rating-color` | — | Active symbol colour |
| `--nana-rating-empty-color` | — | Empty symbol colour |
| `--nana-rating-size` | — | Symbol size (overrides `size`) |
| `--nana-rating-gap` | — | Gap between symbols |

## CSS Parts

| Part | Description |
|---|---|
| `base` | The root container |
| `symbols` | The symbol group |
| `symbol` | A single rating symbol |
| `label` | The value label |

## Accessibility

<ul class="a11y-grid not-content">
  <li>Keyboard accessible</li>
  <li>Screen-reader labels</li>
  <li>Focus-visible states</li>
  <li>ARIA roles and states</li>
  <li>WCAG 2.2 AA contrast</li>
</ul>

## Related components

<ul class="related not-content">
  <li><a href="/components/button/">Button</a></li>
  <li><a href="/components/button-group/">Button Group</a></li>
  <li><a href="/components/icon-button/">Icon Button</a></li>
  <li><a href="/components/input/">Input</a></li>
  <li><a href="/components/textarea/">Textarea</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-rating--docs