Icon Button

Botão de ação compacto representado apenas por um ícone, sem rótulo visível. Compatível com `<form>` nativo via ElementInternals (`mk-icon-button`).

O mk-icon-button é um botão de ação compacto que exibe apenas um ícone, sem rótulo de texto. É sempre da variante ghost — o fundo de hover/active é renderizado via ::before para não interferir nas dimensões do componente. Suporta integração nativa com formulários (type="submit" e type="reset").

Quando usar

Use o mk-icon-button quando:

O espaço é reduzido e o ícone comunica a ação com clareza — fechar, editar, remover.
A ação é secundária ou repetida em listas, toolbars e cabeçalhos.
O rótulo de texto seria redundante diante de um ícone universalmente compreendido.

Prefira alternativas quando:

Houver espaço para rótulo e a ação for importante — use mk-button com leadingIcon.
O ícone, sozinho, não deixar a ação evidente — sempre forneça label.

Padrão

Renderiza um <button> nativo no Shadow DOM com a variante ghost. Forneça sempre label para descrever a ação a leitores de tela.

import { MkIconButton } from '@db1/makuco-ui-react';

<MkIconButton icon="plus" label="Adicionar item" />

<mk-icon-button icon="plus" label="Adicionar item"></mk-icon-button>

Intenções

Use kind="destructive" para ações destrutivas ou irreversíveis — a cor sinaliza risco.

Tipo	Quando usar
Default	Ações neutras ou positivas — adicionar, editar, confirmar.
Destructive	Ações irreversíveis — excluir, remover. Use com ícones como `trash` ou `x`.

<MkIconButton kind="default" icon="plus" label="Adicionar" />
<MkIconButton kind="destructive" icon="trash" label="Excluir" />

<mk-icon-button kind="default" icon="plus" label="Adicionar"></mk-icon-button>
<mk-icon-button kind="destructive" icon="trash" label="Excluir"></mk-icon-button>

Formatos

shape="rounded" usa raio por tamanho; shape="circle" usa raio total.

<MkIconButton shape="rounded" icon="plus" label="Adicionar" />
<MkIconButton shape="circle" icon="plus" label="Adicionar" />

<mk-icon-button shape="rounded" icon="plus" label="Adicionar"></mk-icon-button>
<mk-icon-button shape="circle" icon="plus" label="Adicionar"></mk-icon-button>

Tamanhos

Escale conforme a densidade da interface: xs, sm, md, lg, xl. O ícone interno acompanha o tamanho do botão.

<MkIconButton size="xs" icon="info" label="Informações" />
<MkIconButton size="md" icon="info" label="Informações" />
<MkIconButton size="xl" icon="info" label="Informações" />

<mk-icon-button size="xs" icon="info" label="Informações"></mk-icon-button>
<mk-icon-button size="md" icon="info" label="Informações"></mk-icon-button>
<mk-icon-button size="xl" icon="info" label="Informações"></mk-icon-button>

Desabilitado

<MkIconButton disabled icon="plus" label="Adicionar" />

<mk-icon-button [disabled]="isDisabled" icon="plus" label="Adicionar"></mk-icon-button>

Quando o botão abre e fecha uma linha de detalhe, um painel ou um menu, expanded vira aria-expanded e hasPopup vira aria-haspopup no <button> interno. Sem expanded, o atributo não é renderizado.

<MkIconButton
  icon={aberto ? 'chevron-up' : 'chevron-down'}
  label="Detalhes do pedido"
  expanded={aberto}
  onMkClick={() => setAberto(!aberto)}
/>

<mk-icon-button
  [icon]="aberto ? 'chevron-up' : 'chevron-down'"
  label="Detalhes do pedido"
  [expanded]="aberto"
  (mkClick)="aberto = !aberto"
></mk-icon-button>

Formulários

O mk-icon-button é form-associated: type="submit" aciona form.requestSubmit() e type="reset" aciona form.reset().

<form onSubmit={handleSubmit}>
  <MkIconButton type="submit" icon="check" label="Enviar" />
  <MkIconButton type="reset" icon="x" label="Limpar" />
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-icon-button type="submit" icon="check" label="Enviar"></mk-icon-button>
  <mk-icon-button type="reset" icon="x" label="Limpar"></mk-icon-button>
</form>

Props

Prop	Tipo	Padrão	Descrição
`icon`	`IconName`	—	Ícone Lucide exibido no botão. Obrigatório.
`kind`	`"default" \| "destructive"`	`"default"`	Intenção visual — use `destructive` para ações perigosas.
`shape`	`"rounded" \| "circle"`	`"rounded"`	Formato do botão. `circle` usa raio total.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Tamanho do botão e do ícone interno.
`type`	`"button" \| "submit" \| "reset"`	`"button"`	Tipo do elemento `<button>` nativo.
`disabled`	`boolean`	`false`	Desabilita o botão e impede a interação. Reflete no atributo HTML.
`label`	`string`	—	Texto acessível (`aria-label`). Obrigatório quando não há rótulo visível.
`name`	`string`	—	Atributo `name` do botão nativo (usado em formulários).
`value`	`string`	—	Atributo `value` do botão nativo (usado em formulários).
`expanded`	`boolean`	—	Estado de expansão do conteúdo que o botão abre e fecha, refletido como `aria-expanded` no botão interno. Ausente, o atributo não é renderizado.
`hasPopup`	`"true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"`	—	Tipo de popup que o botão abre, refletido como `aria-haspopup` no botão interno.

Eventos

Evento	Payload	Descrição
`mkClick`	`void`	Emitido ao clicar no botão quando não está `disabled`.

Acessibilidade

Usa <button> nativo internamente — suporte a teclado (Enter / Space) e foco inclusos.
Usa delegatesFocus: chamar focus() no host move o foco para o <button> interno.
Rótulo obrigatório: a prop label define o aria-label. Sempre forneça label para descrever a ação — ícones sozinhos não têm semântica legível por leitores de tela.
expanded e hasPopup chegam ao <button> interno como aria-expanded e aria-haspopup; atributos ARIA postos no host não atravessam o shadow root. aria-controls não é coberto, por ser IDREF.
disabled reflete no atributo HTML (:host([disabled])), sendo ignorado por leitores de tela quando presente.
Foco visível: o anel de foco deve ser perceptível na navegação por teclado. Não remova o outline sem substituí-lo por outro indicador.
Combine com mk-tooltip para reforçar a descrição da ação quando o ícone não for autoexplicativo.

Icon Button

On this page