Icon button
Permite executar uma ação representada apenas por um ícone, sem texto visível, quando o espaço é limitado ou a ação é inequívoca.
- Executar uma ação sem texto: resolver com um ícone que comunica a ação por si só. Ex.: excluir, editar ou fechar.
- Resolver em um espaço reduzido: posicionar a ação onde um botão com texto não cabe, como linhas de uma tabela, cabeçalhos, barras de ferramentas ou células.
- Abrir um menu de ações: exibir ações secundárias a partir de um único disparador. Ex.: o ícone de mais opções que abre um menu.
- Repetir uma ação por linha: oferecer a mesma ação em cada elemento de uma lista, onde o contexto da linha já deixa clara a sua intenção. Ex.: excluir cada item de uma listagem.
- Comunicar com texto imprescindível: quando a ação não pode ser representada de forma inequívoca por um ícone e o texto é necessário para entendê-la. Em vez disso, usar Button com ícone e label.
- Destacar a ação principal: a ação principal da tela ou de um formulário, que precisa de hierarquia e de um label explícito. Em vez disso, usar Button com aparência primary. Ex.: "Salvar alterações".
- Navegar para outra página: levar a outra tela ou ver mais detalhe em vez de executar uma ação. Em vez disso, usar Link. Ex.: "Ver detalhe".
- Agrupar várias ações: reunir várias ações sob um mesmo controle com rótulos visíveis. Em vez disso, usar Menu button.
- Surface: contêiner que delimita a área interativa; define o fundo e a borda do botão em cada estado.
- Icon: símbolo que comunica a ação. É passado pela prop source, com um ícone de @nimbus-ds/icons, e é o único conteúdo visível do botão.
Default: opção padrão para a maioria das ações, quando o botão deve ser lido com clareza como interativo e não se integra a uma estrutura densa. Ex.: editar, excluir ou fechar.
Transparent: quando o botão se integra a uma estrutura densa (barras de ferramentas, linhas de tabela, cabeçalhos) e não deve competir com o conteúdo; a superfície aparece apenas ao interagir. Ex.: as ações por linha de uma listagem.
AI generative (ai-generative): reservar para ações de inteligência artificial ou de Lumi, para distingui-las das ações comuns. Ex.: enviar uma mensagem em um chat assistido por IA.
Large (2.75rem, 44 px): valor recomendado por padrão; cumpre a área tátil mínima de 44×44 px.
Medium (2rem, 32 px): usar em contextos densos onde o botão acompanha outro conteúdo, cuidando para que continue confortável de tocar. Ex.: uma ação inline dentro de uma linha.
O Icon button aparece junto ao conteúdo sobre o qual atua, em contextos onde o espaço é restrito: linhas de uma tabela ou de uma lista, cabeçalhos de seção e barras de ferramentas, o fechamento de um modal ou de uma mensagem, e como disparador de um menu de opções.
Com mais espaço disponível, as ações por elemento podem ser exibidas diretamente na linha, cada uma em seu próprio botão, e combinadas com um Tooltip que revela a ação ao passar o cursor.
Com o espaço reduzido, as ações por elemento se reúnem em um único disparador (⋮) que abre um menu de opções, em vez de ocupar a linha com vários botões.
Compartilhar
Duplicar
Excluir
Suas notas
Escolher um ícone que represente a ação de forma inequívoca, como editar ou excluir.
Configurações
Evitar ícones que não deixam clara a ação que o botão executa no seu contexto.
Usar a aparência AI generative em uma única ação por contexto, a principal de IA (como enviar).
Evitar mais de um botão com aparência AI generative no mesmo contexto: usar apenas um.
Usar apenas os tamanhos Large (2.75rem) ou Medium (2rem).
Evitar tamanhos fora de Medium ou Large: um botão menor não cumpre a área tátil mínima.
- Rótulo acessível: por não ter texto visível, o botão precisa de um aria-label que descreva a ação que executa, não o ícone. Ex.: aria-label="Excluir produto".
- Significado não dependente do ícone: acompanhar o botão com um Tooltip ou reforçar com cor quando a ação é crítica; o ícone sozinho não deve ser a única pista da sua função.
- Navegação por teclado: ao ser renderizado como button, é focável e se ativa com Enter e Espaço; manter uma ordem de foco coerente com o restante da interface.
- Foco visível: conservar o anel de foco que o componente mostra ao navegar com teclado; não removê-lo com estilos próprios.
- Estado desabilitado: usar o atributo disabled para bloquear a ação; o componente atenua o botão e desativa a interação.
- Área tátil: manter o tamanho padrão (2.75rem, 44 px), que cumpre a área tátil mínima recomendada de 44×44 px; ao reduzir size, verificar que continue confortável de tocar.
Instale o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { IconButton } from "@nimbus-ds/components";
import { TiendanubeIcon } from "@nimbus-ds/icons";
const Example: React.FC = () => (
<IconButton source={<TiendanubeIcon size="small" />} />
);
export default Example;As propriedades adicionais são repassadas ao elemento <IconButton>. Consulte a documentação do elemento button para ver a lista de atributos aceitos.
- Button — Para ações que precisam de um label de texto ou de hierarquia visual, com ou sem ícone.
- Link — Para navegar entre páginas ou ver mais detalhes, em vez de executar uma ação.
- Menu button — Para agrupar várias ações sob um mesmo controle com rótulos visíveis.
IconButton
| Name | Type | Default | Description |
|---|---|---|---|
as | 'button' | 'button' | Type of html tag to create for the Icon Button component. |
source* | React.ReactNode | The SVG contents to display in the Icon button. | |
color | 'ai-generative' | 'neutral-textHigh' | Set the color for the inner Icon fill. |
appearance | 'ai-generative' | AI gradient background appearance for the button container. When provided, container color/border sprinkles are ignored in favor of gradient styles. | |
size | string | '2.75rem' | The size of the component. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "active": "value", "hover": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value", "xxl": "value" }' |
borderColor | 'ai-generativeSurface' | '{ xs: "neutral-interactive", active: "neutral-interactivePressed", hover: "neutral-interactiveHover", focus: "primary-interactive" }' | The borderColor property sets the color of the icon button's four borders. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "active": "value", "hover": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value", "xxl": "value" }' |
backgroundColor | 'ai-generativeSurface' | '{ xs: "neutral-surface", active: "neutral-interactive", hover: "neutral-surfaceHighlight" }' | The backgroundColor property sets the background color of the icon button. This is a responsive property and you can have the options below available for you to use. '{ "focus": "value", "active": "value", "hover": "value", "xs": "value", "md": "value", "lg": "value", "xl": "value", "xxl": "value" }' |
IconButton.Skeleton
| Name | Type | Default | Description |
|---|---|---|---|
width | string | Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own. | |
className | string | ||
height | string | Height of the skeleton. Useful when you don't want to adapt the skeleton to a text element but for instance a card. | |
data-testid | string | This is an attribute used to identify a DOM node for testing purposes. |