Pular para o conteúdo
Ações

IconButton

/componentes/icon-button.mdmarkdown cru, para quem lê com agent em vez de olho

Variantes

Tamanhos

Com dica

Estados

Importar
import { IconButton } from '@rivocode/ui'

Quando usar

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.

<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.

<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.

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:

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

API

PropTipoPadrão
labelobrigatória

O nome do botao, obrigatorio: e o que o leitor de tela anuncia, e o texto da dica quando `tooltip` esta ligado.

stringsem padrão
aria-label

Recusado pelo tipo: o nome acessivel tem um caminho so, que e o `label`.

undefinedsem padrão
aria-labelledby

Recusado pelo tipo, pelo mesmo motivo do `aria-label`.

undefinedsem padrão
loading

Desabilita e anuncia ocupado enquanto uma acao esta em andamento.

booleanfalse
refRef<HTMLButtonElement>sem padrão
render

Troca o elemento renderizado mantendo a aparencia.

ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
shape"default""pill"nullsem padrão
size

O lado do quadrado, lido de `--rc-control-*`: encolhe com a densidade.

"lg""md""sm""md"
tone

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`.

"danger" | "neutral"sem padrão
tooltip

Mostra o `label` numa dica ao pousar o ponteiro ou focar pelo teclado.

booleanfalse
tooltipSide

O lado em que a dica abre, quando `tooltip` esta ligado.

"bottom""left""right""top"sem padrão
variant"danger""ghost""outline""primary""secondary"nullsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.