IconButton
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.
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:
<IconButton label="Excluir pedido" variant="ghost" onPress={excluir}>
{({ color, size }) => <Trash2 color={color} size={size} />}
</IconButton>
API
| Prop | Tipo | Padrão |
|---|---|---|
labelobrigatóriaO nome do botao, obrigatorio: e o que o leitor de tela anuncia, e o texto da dica quando `tooltip` esta ligado. | string | sem padrão |
aria-labelRecusado pelo tipo: o nome acessivel tem um caminho so, que e o `label`. | undefined | sem padrão |
aria-labelledbyRecusado pelo tipo, pelo mesmo motivo do `aria-label`. | undefined | sem padrão |
loadingDesabilita e anuncia ocupado enquanto uma acao esta em andamento. | boolean | false |
ref | Ref<HTMLButtonElement> | sem padrão |
renderTroca o elemento renderizado mantendo a aparencia. | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
shape | "default""pill"null | sem padrão |
sizeO lado do quadrado, lido de `--rc-control-*`: encolhe com a densidade. | "lg""md""sm" | "md" |
toneO 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 |
tooltipMostra o `label` numa dica ao pousar o ponteiro ou focar pelo teclado. | boolean | false |
tooltipSideO lado em que a dica abre, quando `tooltip` esta ligado. | "bottom""left""right""top" | sem padrão |
variant | "danger""ghost""outline""primary""secondary"null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.