# IconButton

Botão que só tem ícone. É o caminho recomendado para a ação de linha de tabela,
o fechar de painel, o baixar, o editar: tudo o que cabe num quadrado.

```tsx
<IconButton variant="ghost" label="Excluir tarefa">
  <Trash2 />
</IconButton>
```

**O `label` é obrigatório, e o tipo não deixa esquecer.** Ele vira o nome
acessível do botão, e é a única porta para isso: `aria-label` e
`aria-labelledby` saem do tipo, para o nome não ter dois caminhos que divergem.
Diga a ação, e não o desenho: "Excluir tarefa", e não "Lixeira". Botão sem nome é
anunciado como "botão", e mais nada.

O ícone sai `aria-hidden`, porque quem nomeia é o `label`, e o tamanho dele vem
da peça: 16px no `sm` e no `md`, 20px no `lg`. Não precisa passar `size` para o
ícone do lucide.

## Variantes e tamanhos

As mesmas cinco variantes do `Button` (`primary`, `secondary`, `outline`,
`ghost`, `danger`) e a mesma `shape="pill"`, lidas das mesmas classes: o
`IconButton` é um `Button` por dentro, e não uma cópia dele. O que muda é o
tamanho. `sm`, `md` e `lg` são quadrados cujo lado é a altura de controle do
token (`--rc-control-sm`, `-md`, `-lg`), então o botão de ícone encolhe junto
com o campo ao lado no modo compacto e nunca fica mais alto que ele.

## Com dica

`tooltip` mostra o `label` numa dica ao pousar o ponteiro ou focar pelo teclado.
Ligue quando o ícone não for universal. Um lápis se lê sozinho, e uma folha
genérica não diz se abre o PDF ou a planilha.

```tsx
<IconButton variant="ghost" label="Ver o anexo da tarefa" tooltip>
  <FileText />
</IconButton>
```

A dica **não entra no nome**: ela repete o `label`, e amarrá-la por
`aria-describedby` faria o leitor de tela dizer a mesma frase duas vezes. Ela é
para quem enxerga e ainda não conhece o ícone. `tooltipSide` escolhe o lado.

## Carregando e desabilitado

`loading` troca o ícone pela espera no mesmo quadrado, trava o clique e anuncia
`aria-busy`, e o nome continua o mesmo: a pessoa que ouve sabe o que está
esperando. `disabled` é o do `Button`, com o fundo, a cor e o contorno de desabilitado.

## Como link

`render={<a href="..." />}` troca o elemento, como no `Button`, e o `label`
continua nomeando o link.

## Como gatilho

No sentido contrário, o `IconButton` é o `render` de um gatilho:
`<MenuTrigger render={<IconButton label="Mais ações" />}>`, com o ícone como
filho do `MenuTrigger`. Por isso `children` é opcional no tipo: o gatilho é
quem entrega o ícone. Fora desse uso, passe o ícone sempre.

## Quando não usar

Se há espaço para a palavra, use `Button` com texto: o rótulo escrito é mais
claro do que qualquer ícone com dica, e é o único dos dois que funciona no
toque. Ação principal de tela quase nunca é só ícone.

Botão que fica apertado (negrito, alinhamento, modo de exibição) é `Toggle`: o
`IconButton` dispara uma ação e não guarda estado, e o `Toggle` diz
`aria-pressed`.

O `Button` não desenha quadrado de ícone: `size` nele é só `sm`, `md`, `lg` e
`xl`, todos com rótulo escrito. Botão só com ícone é sempre esta peça, porque
ela exige o nome, tem os três tamanhos e resolve a espera sem alargar o
quadrado.

## No React Native

Traduz, com o nome obrigatório do mesmo jeito e com o mesmo nome: `label`, e o tipo recusa o botão sem ele. O `accessibilityLabel` não entra: o nome é um só, o `label`, e é ele que vira o `accessibilityLabel` do `Pressable`.

**O alvo de toque nunca fica abaixo de 44pt.** `md` é o quadrado de 44 e `lg` o de 48; o `sm` desenha 32 e ganha `hitSlop` de 6 nos quatro lados, que devolve os 44 sem crescer o desenho. As variantes são as do `Button` nativo (`primary`, `secondary`, `ghost`, `outline`, `danger`), lidas das mesmas classes: só `shape` não atravessa, pelo mesmo motivo de lá.

**Não há `tooltip`.** A dica aparece ao pousar o ponteiro, e no toque não existe pousar. Se o ícone não se lê sozinho, o botão pede texto: use `Button`.

O ícone entra como filho, e a forma que pinta na cor da variante é a função, porque a cor não desce da `View` para o SVG:

```tsx
<IconButton label="Excluir pedido" variant="ghost" onPress={excluir}>
  {({ color, size }) => <Trash2 color={color} size={size} />}
</IconButton>
```

## Importação

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

## Exemplos

### Variantes

```tsx
import { IconButton } from '@rivocode/ui'
import { Download, Pencil, RefreshCw, Trash2 } from 'lucide-react'

export function Variants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <IconButton label="Nova tarefa">
        <Pencil />
      </IconButton>
      <IconButton variant="secondary" label="Baixar PDF">
        <Download />
      </IconButton>
      <IconButton variant="outline" label="Atualizar lista">
        <RefreshCw />
      </IconButton>
      <IconButton variant="ghost" label="Editar tarefa">
        <Pencil />
      </IconButton>
      <IconButton variant="danger" label="Excluir tarefa">
        <Trash2 />
      </IconButton>
    </div>
  )
}
```

### Tamanhos

```tsx
import { IconButton } from '@rivocode/ui'
import { Download, Pencil, RefreshCw, Trash2 } from 'lucide-react'

export function Sizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <IconButton size="sm" variant="secondary" label="Baixar PDF">
        <Download />
      </IconButton>
      <IconButton size="md" variant="secondary" label="Baixar PDF">
        <Download />
      </IconButton>
      <IconButton size="lg" variant="secondary" label="Baixar PDF">
        <Download />
      </IconButton>
      <IconButton shape="pill" variant="secondary" label="Baixar PDF">
        <Download />
      </IconButton>
    </div>
  )
}
```

### Com dica

```tsx
import { IconButton } from '@rivocode/ui'
import { Download, Pencil, RefreshCw, Trash2 } from 'lucide-react'

export function WithTooltip() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <IconButton variant="ghost" label="Editar tarefa" tooltip>
        <Pencil />
      </IconButton>
      <IconButton variant="ghost" label="Excluir tarefa" tooltip tooltipSide="bottom">
        <Trash2 />
      </IconButton>
    </div>
  )
}
```

### Estados

```tsx
import { IconButton } from '@rivocode/ui'
import { Download, Pencil, RefreshCw, Trash2 } from 'lucide-react'

export function States() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <IconButton variant="secondary" label="Sincronizando tarefas" loading>
        <RefreshCw />
      </IconButton>
      <IconButton variant="secondary" label="Baixar PDF" disabled>
        <Download />
      </IconButton>
    </div>
  )
}
```

### Como link

```tsx
import { IconButton } from '@rivocode/ui'
import { Download, Pencil, RefreshCw, Trash2 } from 'lucide-react'

export function AsLink() {
  return (
    <IconButton variant="ghost" label="Baixar o anexo da tarefa" render={<a href="#" />}>
      <Download />
    </IconButton>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | sim |  | - | O nome do botao, obrigatorio: e o que o leitor de tela anuncia, e o texto da dica quando `tooltip` esta ligado. |
| `aria-label` | `undefined` |  |  | - | Recusado pelo tipo: o nome acessivel tem um caminho so, que e o `label`. |
| `aria-labelledby` | `undefined` |  |  | - | Recusado pelo tipo, pelo mesmo motivo do `aria-label`. |
| `loading` | `boolean` |  | `false` | - | Desabilita e anuncia ocupado enquanto uma acao esta em andamento. |
| `ref` | `Ref<HTMLButtonElement>` |  |  | - |  |
| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento renderizado mantendo a aparencia. |
| `shape` | `"default" \| "pill" \| null` |  |  | - |  |
| `size` | `"lg" \| "md" \| "sm"` |  | `"md"` | - | O lado do quadrado, lido de `--rc-control-*`: encolhe com a densidade. |
| `tone` | `"danger" \| "neutral"` |  |  | - | O tom do `ghost`: `danger` escreve em `danger-text` e, sob o ponteiro e no clique, pinta `danger-subtle` - o destrutivo discreto da linha da tabela, ao lado de outros `ghost`. |
| `tooltip` | `boolean` |  | `false` | - | Mostra o `label` numa dica ao pousar o ponteiro ou focar pelo teclado. |
| `tooltipSide` | `"bottom" \| "left" \| "right" \| "top"` |  |  | - | O lado em que a dica abre, quando `tooltip` esta ligado. |
| `variant` | `"danger" \| "ghost" \| "outline" \| "primary" \| "secondary" \| null` |  |  | - |  |

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

## Ver também

- [ActionBar](/componentes/action-bar.md)
- [Button](/componentes/button.md)
- [ButtonGroup](/componentes/button-group.md)
- [Clipboard](/componentes/clipboard.md)
- [ScrollToTop](/componentes/scroll-to-top.md)
- [Toggle](/componentes/toggle.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
