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

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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'.
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.
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
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).
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.
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
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
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.
Tipo	"block" | "circle" | "pill"
Valor padrão	---

type

Atributo	type
Descrição	Define o tipo de botão, especificando seu comportamento padrão.
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).

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

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.

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">
  <br-icon icon-name="check"></br-icon>
  Salvar
</br-button>