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-button é o controle fundamental de ação e acionamento do GovBR-DS. Desenvolvido para permitir que pessoas usuárias executem comandos, confirmem intenções e submetam ou redefinam formulários, ele oferece retorno visual imediato e conformidade com diretrizes de acessibilidade WAI-ARIA.

Para que serve

• Disparo de ações do sistema: Executa comandos locais ou assíncronos na interface (ex.: salvar dados, abrir modais, aplicar filtros).
• Integração com formulários: Suporta os tipos nativos de botão (type="button", type="submit" e type="reset"), integrando-se ao ciclo de submissão do formulário HTML.
• Variantes e hierarquia visual: Oferece diferentes estilos visuais (primário, secundário), densidades e opções de exibição (com ícone, somente ícone, circular e em bloco).
• Feedback de carregamento e estado: Informa estados de processamento com o modo loading e desativação acessível com disabled.

Quando utilizar

• Utilize quando:
  • A pessoa usuária precisar executar uma ação imediata ou submeter dados dentro do fluxo atual da página.
  • For necessário acionar componentes flutuantes (como abrir br-modal, alternar br-collapse ou expandir br-dropdown).
• Evite e prefira outro componente quando:
  • A ação tiver como objetivo navegar para outra página ou alterar a URL do navegador (prefira br-link ou um elemento <a> nativo).
  • O controle representar uma escolha de valor fixo entre poucas opções mutuamente exclusivas (prefira br-radio ou br-radio-group).

Estrutura e Slots

O br-button é um controle direto e autônomo:

• default: Slot para inserção do texto do rótulo, ícones de apoio (br-icon) ou composições personalizadas.

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ão

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

active

Atributo	active
Descrição	Estado ativo canônico. Quando informado, tem precedência sobre isActive.
Tipo	boolean
Valor padrão	---

ariaControls

Atributo	aria-controls
Descrição	Referência ao ID do elemento que o botão controla. Use em conjunto com ariaExpanded para relacionar o botão ao painel que ele expande/recolhe.
Tipo	string
Valor padrão	null

ariaExpanded

Atributo	aria-expanded
Descrição	Indica se um elemento controlado pelo botão está expandido ou recolhido. Use em botões que abrem menus, acordeões ou outros painéis expansíveis. O valor deve ser 'true' ou 'false'.
Tipo	string
Valor padrão	null

ariaHaspopup

Atributo	aria-haspopup
Descrição	Indica que o botão abre um menu, listbox, tree, grid ou dialog. Os valores permitidos são: 'true', 'menu', 'listbox', 'tree', 'grid' ou 'dialog'. Valores inválidos são removidos do elemento interno.
Tipo	"dialog" | "grid" | "listbox" | "menu" | "tree" | "true"
Valor padrão	null

ariaLabel

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

ariaPressed

Atributo	aria-pressed
Descrição	Define o estado de pressionado do botão. Este atributo é usado para indicar se o botão está atualmente pressionado ou não. É especialmente útil para botões que podem ser alternados entre os estados pressionado e não pressionado. O valor deve ser 'true' ou 'false'.
Tipo	string
Valor padrão	null

colorMode

Atributo	color-mode
Descrição	Define se o botão usará um esquema de cores escuro. Valores inválidos são ignorados.
Tipo	"dark"
Valor padrão	---

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()

customTabIndex Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	custom-tab-index
Depreciação	Use o atributo/propriedade nativo tabIndex do host.
Descrição	Define o índice de tabulação do botão. Útil para remover o botão da sequência de tabulação (tabindex="-1") quando ele é puramente decorativo ou o foco é gerenciado por um componente pai. Aceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.
Tipo	number
Valor padrão	---

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'

disabled

Atributo	disabled
Descrição	Desabilita a interação com o componente.
Tipo	boolean
Valor padrão	false

emphasis

Atributo	emphasis
Descrição	Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes. Valores inválidos são ignorados.
Tipo	"primary" | "secondary" | "tertiary"
Valor padrão	---

isActive Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-active
Depreciação	Use active.
Descrição	Indica se o botão está no estado ativo. Se definido como verdadeiro, o botão será exibido como ativo.
Tipo	boolean
Valor padrão	false

isLoading Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-loading
Depreciação	Use loading.
Descrição	Aplica o estado de "progresso" ao botão. O botão exibirá um indicador de carregamento ou progresso.
Tipo	boolean
Valor padrão	false

loading

Atributo	loading
Descrição	Estado de carregamento canônico. Quando informado, tem precedência sobre isLoading.
Tipo	boolean
Valor padrão	---

shape

Atributo	shape
Descrição	Define o formato do botão. Valores inválidos são ignorados.
Tipo	"block" | "circle" | "pill"
Valor padrão	---

type

Atributo	type
Descrição	Define o tipo de botão, especificando seu comportamento padrão. Valores inválidos usam button.
Tipo	"button" | "reset" | "submit"
Valor padrão	---

value

Atributo	value
Descrição	Define o valor inicial do botão em um formulário.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"default"	Slot para o rótulo ou conteúdo do botão.

CSS Shadow Parts

Nome	Descrição
"button"	Parte para o elemento button interno, usada para estilos customizados via ::part(button).

Acessibilidade

O componente renderiza um <button> nativo no Shadow DOM (part="button"), então herda papel, foco e teclado do elemento: Enter e Espaço acionam o botão e ele entra naturalmente na ordem de tabulação.

Nome acessível

O nome vem do conteúdo do slot padrão (o rótulo visível). Para botões só com ícone — inclusive shape="circle" — use aria-label; o componente emite um aviso no console quando um botão circular não tem aria-label. O nome visível e o nome acessível não devem divergir.

Estados

• disabled (ou desabilitado por um <fieldset disabled> ancestral) aplica o atributo nativo disabled e também aria-disabled="true", mantendo o botão perceptível por leitores de tela mesmo sem receber foco.
• loading/isLoading define aria-busy="true" e adiciona um texto visualmente oculto "Carregando"; mantenha o rótulo original enquanto carrega.
• Para botão de alternância, defina aria-pressed ("true"/"false").
• Para botão que expande um painel, use aria-expanded junto de aria-controls apontando para o id do painel.
• Para gatilho de menu ou diálogo, use aria-haspopup (menu, listbox, dialog, true…). Esses atributos são refletidos e repassados ao <button> interno.

Foco e teclado

O foco fica no <button> interno; focus() no host coloca o usuário no botão. tabindex definido no host é repassado — não use tabindex positivo. type é button por padrão; use type="submit"/type="reset" apenas quando o botão deve operar o <form> do consumidor (o componente é formAssociated).

Movimento

Transições e o indicador de carregamento respeitam prefers-reduced-motion: reduce.

Eventos nativos

Elemento HTML de referência

br-button encapsula um <button>. O host representa a ação e preserva ativação, foco e os tipos button, submit e reset.

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
click	ativação por ponteiro, Enter ou Space	Sim	Sim	Sim	Sim	O alvo externo é o host.
reset	botão reset ativa o reset	Sim	Não	Sim	No <form>	O evento pertence ao formulário.
submit	botão submit ativa formulário válido	Sim	Não	Sim	No <form>	O evento pertence ao formulário.

Eventos não aplicáveis ou não suportados

Evento	Situação	Motivo	Alternativa
input / change	Não aplicável	Botão não mantém valor editável.	Ouça click ou o evento do formulário.

Atributos nativos

br-button é um form-associated custom element. type, value, disabled, name e form participam do contrato de formulário; form e name podem ser atributos nativos do host sem props dedicadas.

São suportados os tipos button, submit e reset. formaction, formenctype, formmethod, formtarget e formnovalidate não são suportados porque o componente não é um submitter nativo completo. autofocus permanece atributo global do host.

Dependências

Usado por

• br-breadcrumb
• br-carousel
• br-cookiebar
• br-date-picker
• br-header
• br-header-function
• br-header-list
• br-input
• br-loading
• br-menu
• br-menu-header
• br-message
• br-modal
• br-notification-header
• br-pagination
• br-tag
• br-time-picker
• br-tooltip
• br-upload
• br-wizard

Gráfico

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

O elemento br-button continua existindo. A principal mudança é que o texto e o ícone passaram a ser conteúdo do componente, enquanto a aparência usa propriedades semânticas.

Propriedades

API 1.x	API 2.x	Ação na migração
block / circle	shape	Converta para o valor de forma equivalente.
icon	slot/conteúdo do botão	Mova o ícone para o conteúdo do componente.
inverted	color-mode	Renomeie a propriedade.
label	conteúdo padrão	Mova o texto para dentro do elemento.
loading	loading	Mantenha.
submit	type="submit"	Use o atributo nativo do botão.
type	emphasis	Use emphasis para a aparência; preserve type="submit" apenas para o comportamento nativo de formulário.

Exemplo

1.x:

<br-button label="Salvar" type="primary" icon="check" submit></br-button>

2.x:

<br-button emphasis="primary" type="submit">
  <i class="fas fa-check" aria-hidden="true"></i>
  Salvar
</br-button>