# Rating

Nota em estrelas: como foi o atendimento, quanto a pessoa gostou do produto, a
média que os outros deram. Serve para **escolher** a nota e para **exibir** a
média, e as duas coisas saem com a leitura de tela certa.

```tsx
const [nota, setNota] = useState(0)

<Rating value={nota} onValueChange={setNota} />
```

`value` é a nota, e `0` quer dizer nenhuma. Sem `value`, a peça guarda a nota
sozinha a partir de `defaultValue`. `max` diz quantas estrelas, e o padrão é
cinco.

## Para o leitor de tela e para o teclado

A escolha é um `radiogroup`, o padrão da APG para rating: cada estrela é uma
opção com o nome da nota ("1 estrela", "3 estrelas"), e o grupo se chama
"Avaliação". Um `aria-labelledby` apontando para a pergunta da tela toma o
lugar do nome padrão, e é o jeito certo quando a pergunta está escrita acima.

- **Tab** entra pela nota marcada, ou pela primeira quando ainda não há nota.
- **Setas** andam uma estrela (meia, com `allowHalf`) e param nas pontas. Em
  `rtl` a seta da esquerda é a que sobe, como a pessoa vê, e o preenchimento
  nasce da borda da direita.
- **Home** e **End** vão para a menor e para a maior nota.
- **Espaço** e **Enter** escolhem a estrela em foco.

Com o ponteiro em cima, as estrelas mostram a prévia da nota que o clique daria,
e a prévia some quando o ponteiro sai. A prévia não muda o `value`.

```tsx
<p id="pergunta">Como foi a entrega?</p>
<Rating aria-labelledby="pergunta" value={nota} onValueChange={setNota} />
```

## Meia estrela e limpar

`allowHalf` divide cada estrela em duas notas: a metade do início da leitura
(a esquerda, ou a direita em `rtl`) é a nota `n - 0,5`, e as setas andam de
meio em meio. As metades ganham nome próprio ("Meia estrela", "2,5 estrelas"),
uma opção cada para o leitor de tela. O alvo do ponteiro continua a estrela
inteira, com os mesmos 24px ou mais: a metade sai de onde o ponteiro caiu
dentro dela.

`clearable` faz o clique na nota já escolhida voltar a zero, e `onValueChange`
chega com `0`. Nasce desligado: na maioria das telas a nota, uma vez dada, só se
troca.

```tsx
<Rating allowHalf clearable value={nota} onValueChange={setNota} />
```

## A média, só leitura

`readOnly` exibe sem deixar escolher. Aceita qualquer fração (4,3 pinta 30% da
quinta estrela) e sai como **uma imagem só** para o leitor de tela, com o nome
"4,3 de 5". Cinco estrelas lidas uma a uma não dizem a média; a frase diz.

```tsx
<Rating readOnly value={4.3} size="sm" />
```

## Cor, tamanho e ícone

A estrela cheia pinta em `warning` e a vazia em `border-strong`. As duas são
fronteira de objeto gráfico, e as duas estão medidas a 3:1 sobre `bg`,
`surface` e `surface-raised`, nos dois temas. Desabilitada, a cheia vira
`fg-disabled` e a vazia `border-disabled`.

`size` troca a estrela (`sm`, `md`, `lg`), e a caixa de cada uma nunca fica
abaixo de 24px de alvo. `icon` troca o desenho por outro ícone do lucide, como
`<Heart />`: o cheio sai com `fill`, então o ícone precisa ter área.

`name` põe a nota num `input` escondido, para o `<form>` enviar junto.

## Partes

`classNames` alcança cada nó pelo nome: `item` (a caixa de cada estrela),
`empty` (o desenho vazio) e `filled` (o desenho cheio, recortado pela nota).

## Textos

`labels` troca o que o leitor de tela ouve: `group` (o nome do grupo), `item`
(a função que diz o nome de cada nota) e `value` (a função que diz a média no
modo só leitura).

## Quando não usar

- **Número que precisa ser exato** é `NumberField`. Estrela é opinião, e o
  intervalo é pequeno: nota de 0 a 10 com decimal não cabe em estrela.
- **Faixa contínua**, como desconto ou prazo, é `Slider`. O `Slider` arrasta
  por uma régua; o `Rating` escolhe entre poucos degraus que têm nome.
- **Escolha entre opções que não são nota** ("Ruim", "Bom", "Ótimo" escritos)
  é `RadioGroup`, ou `ToggleGroup` quando os botões ficam lado a lado. Estrela
  só funciona quando mais é melhor.
- **Medida do sistema**, como uso do plano ou força de senha, é `Meter`. O
  `Meter` mostra uma quantidade; o `Rating` mostra uma opinião.

## No React Native

Traduz, com os mesmos `max`, `allowHalf`, `clearable`, `readOnly` e `size`. O `value` é controlado, como em todo o pacote nativo, e sem `onValueChange` a peça só exibe.

**Para o leitor de tela, as estrelas são um controle só.** No web a escolha é um `radiogroup` com uma opção por estrela; aqui o grupo é `adjustable`, o mesmo contrato do `Slider`: o VoiceOver e o TalkBack dizem "Avaliação, 3 estrelas", e o gesto de subir e descer anda uma estrela (meia, com `allowHalf`). Cinco paradas de foco para uma nota seriam cinco toques de navegação para chegar ao botão de enviar.

**O alvo de toque de cada estrela é sempre 44pt.** O `size` troca só o desenho. Com `allowHalf`, o toque na metade de início da leitura dá a meia estrela: a da esquerda, ou a da direita quando o aparelho lê da direita para a esquerda. O preenchimento também começa desse lado, e o gesto de subir continua subindo a nota. Não há prévia: no toque não existe pousar.

A estrela padrão é o `Star` do `lucide-react-native`, o mesmo do web, cheia em `warning` e vazada em `border-strong`. Para outro desenho, a função recebe a cor já resolvida, o tamanho e a camada: `icon={({ color, size }) => <Heart color={color} fill={color} size={size} />}`.

```tsx
<Rating value={nota} onValueChange={setNota} allowHalf />
```

As partes vestem pelo mesmo `classNames` do web: `item`, `empty` e `filled`. As duas últimas vestem a estrela da casa, que é texto; com `icon`, a cor chega pela função.

## Importação

```tsx
import { Rating } from '@rivocode/ui'
```

## Exemplos

### Escolher a nota

```tsx
import { Rating } from '@rivocode/ui'
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function Choose() {
  const [value, setValue] = useState(0)

  return (
    <div className="flex flex-col gap-2">
      <p id="nota-atendimento" className="text-sm font-medium text-fg">
        Como foi o atendimento?
      </p>
      <Rating aria-labelledby="nota-atendimento" value={value} onValueChange={setValue} clearable />
      <p className="text-sm text-fg-muted">
        {value === 0 ? 'Nenhuma nota ainda.' : `Nota ${value} de 5. Clique de novo para limpar.`}
      </p>
    </div>
  )
}
```

### Meia estrela

```tsx
import { Rating } from '@rivocode/ui'
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function Half() {
  const [value, setValue] = useState(3.5)

  return (
    <div className="flex items-center gap-3">
      <Rating allowHalf value={value} onValueChange={setValue} aria-label="Nota do produto" />
      <span className="tabular-nums text-sm text-fg-muted">
        {value.toLocaleString('pt-BR')}
      </span>
    </div>
  )
}
```

### Média, só leitura

```tsx
import { Rating } from '@rivocode/ui'
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function Average() {
  return (
    <div className="flex items-center gap-2">
      <Rating readOnly value={4.3} size="sm" />
      <span className="text-sm text-fg">4,3</span>
      <span className="text-sm text-fg-muted">(128 avaliações)</span>
    </div>
  )
}
```

### Tamanhos, ícone e desabilitado

```tsx
import { Rating } from '@rivocode/ui'
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function Sizes() {
  return (
    <div className="flex flex-col gap-3">
      <Rating size="sm" defaultValue={3} />
      <Rating size="md" defaultValue={3} />
      <Rating size="lg" defaultValue={3} />
      <Rating icon={<Heart />} max={3} defaultValue={2} labels={{ group: 'Gostou?' }} />
      <Rating disabled defaultValue={2} />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `allowHalf` | `boolean` |  | `false` | - | Aceita meia estrela: as setas andam de meio em meio, e o leitor de tela ouve uma opcao por meia nota. |
| `classNames` | `Partial<Record<"empty" \| "filled" \| "item", string>>` |  |  | - |  |
| `clearable` | `boolean` |  | `false` | - | Clicar de novo na nota escolhida volta a nenhuma. |
| `defaultValue` | `number` |  | `0` | - | A nota ao montar, quando ninguem controla. |
| `disabled` | `boolean` |  | `false` | - | Desliga a escolha. |
| `icon` | `ReactNode` |  |  | - | Troca a estrela por outro icone do lucide (`<Heart />`, `<ThumbsUp />`). |
| `labels` | `Partial<RatingLabels>` |  |  | - | Os textos que o leitor de tela ouve: o nome do grupo, o de cada nota e o da media. |
| `max` | `number` |  | `5` | - | Quantas estrelas. |
| `name` | `string` |  |  | - | Nome do campo num `<form>`: a nota vai num `input` escondido. |
| `onValueChange` | `((value: number) => void)` |  |  | - | Chamado com a nota nova: pelo clique, pelas setas, por Home e End. |
| `readOnly` | `boolean` |  | `false` | - | So exibe: a media de um produto, a nota que outra pessoa deu. |
| `size` | `"lg" \| "md" \| "sm"` |  | `"md"` | - | O tamanho da estrela. |
| `value` | `number` |  |  | - | A nota escolhida, controlada. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
