Magic Button

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O br-magic-button é o botão de ação flutuante (FAB) que destaca a ação primária ou mais frequente da tela.

Pode ser exibido apenas com ícone (formato circular) ou expandido com texto descritivo.

<br-magic-button icon="fa6-solid:plus" aria-label="Novo item"></br-magic-button>
<br-magic-button icon="fa6-solid:plus">Criar documento</br-magic-button>

Quando usar

• Ação principal e dominante da tela em dispositivos móveis ou interfaces focadas em uma tarefa única.

Quando evitar

• Múltiplas ações de mesma importância: use br-button.
• Ações secundárias ou destrutivas.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

ariaLabel

Atributo	aria-label
Descrição	Define o rótulo acessível usado por tecnologias assistivas.
Tipo	string
Valor padrão	''

circle

Atributo	circle
Descrição	Define se o botão terá formato circular. Aplica contorno arredondado completo quando true e não houver label.
Tipo	boolean
Valor padrão	false

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

icon

Atributo	icon
Descrição	Ícone como identificador Iconify (ex.: fa6-solid:star) ou nome simples (ex.: question, resolvido como fa6-solid:question no registro SVG local), renderizado pelo br-icon. Para classes CSS (ex.: Font Awesome) ou SVGs personalizados, use o slot icon, a forma preferida. Uso descontinuado: classes CSS nesta prop (ex.: fas fa-star) não são exibidas no Shadow DOM e geram aviso.
Tipo	string
Valor padrão	''

label

Atributo	label
Descrição	Texto do rótulo do botão. Utilizado como conteúdo principal quando presente.
Tipo	string
Valor padrão	''

Slots

Nome	Descrição
"default"	Conteúdo interno do botão (texto ou ícone).
"icon"	Ícone customizado do botão. Quando utilizado, a prop icon é ignorada.

CSS Shadow Parts

Nome	Descrição
"button"	Elemento button interno.
"container"	Wrapper principal do magic-button.

Dependências

Depende de

• br-icon

Gráfico

Migração de <br-magic-button> (1.x → 2.x)

A API principal do magic button permaneceu compatível. A mudança relevante é que tooltip não é mais configurado por propriedades próprias.

Propriedades

API 1.x	API 2.x	Ação na migração
label, icon, density, circle, ariaLabel	mesmos nomes	Mantenha.
tooltipText, tooltipPlace, tooltipType, tooltipTimer	—	Remova e componha um br-tooltip separado, se necessário.

Exemplo

1.x:

<br-magic-button label="Ajuda" tooltip-text="Abrir ajuda">
  <i slot="icon" class="fas fa-question" aria-hidden="true"></i>
</br-magic-button>

2.x:

<br-tooltip>
  <br-magic-button slot="trigger" label="Ajuda">
    <i slot="icon" class="fas fa-question" aria-hidden="true"></i>
  </br-magic-button>
  <span slot="content">Abrir ajuda</span>
</br-tooltip>