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 componente br-magic-button é o botão de ação flutuante (Floating Action Button - FAB) do GovBR-DS, projetado para destacar a ação primária ou mais relevante da tela, mantendo-se acessível e visível durante a navegação.

Para que serve

• Destaque da ação principal: Cria um ponto focal imediato para a ação central de uma tela (ex.: "Nova mensagem", "Criar solicitação", "Adicionar item").
• Posicionamento persistente ou integrado: Pode ser fixado em um canto da tela (em dispositivos móveis) ou posicionado no fluxo de leitura de painéis e tabelas.
• Modos circular e expandido: Suporta visual circular compacto com ícone ou versão expandida com texto explicativo.

Quando utilizar

• Utilize quando:
  • Houver uma única ação dominante que represente o principal objetivo da pessoa usuária naquela tela.
  • Em aplicações móveis ou responsivas que necessitem de um atalho de fácil alcance para os polegares.
• Evite e prefira outro componente quando:
  • Houver múltiplas ações de importância equivalente (prefira uma barra de botões com br-button).
  • A ação for secundária, destrutiva ou de cancelamento.

Estrutura e Slots

O br-magic-button é um controle direto:

• default: Slot para rótulo de texto ou conteúdo interno do botão.
• icon: Slot para personalização do ícone de ação (como br-icon).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoCircular com ícone

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>