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-button executa uma ação: salvar, enviar um formulário, abrir um modal, aplicar um filtro.

O texto e o ícone vão dentro do botão. A aparência é definida por emphasis (primary, secondary ou tertiary) e shape (circle, block ou pill).

<br-button emphasis="primary" type="submit">Enviar</br-button>

<br-button shape="circle" aria-label="Fechar">
  <br-icon src="/icones/fechar.svg"></br-icon>
</br-button>

O tipo padrão é button. Use type="submit" ou type="reset" para agir sobre o formulário em que o botão está. Durante uma operação demorada, ative loading.

Quando usar

• Executar uma ação na página atual.
• Abrir modal, menu ou painel.

Quando evitar

• Para ir a outra página: use br-link ou <a>.
• Para escolher entre opções: use br-radio ou br-checkbox.

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

active

Atributo	active
Descrição	Estado ativo atual. 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 atual. 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. Quando omitido, usa button; valores inválidos também usam button e geram aviso no console.
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 botão usa um <button> nativo: entra na ordem de tabulação e é acionado com Enter e Espaço.

• Nome: vem do texto do botão. Em botão só com ícone, inclusive shape="circle", informe aria-label. Sem isso, o botão circular avisa no console.
• Desabilitado: com disabled, ou dentro de um <fieldset disabled>, o botão não recebe foco e continua sendo anunciado como desabilitado.
• Carregando: loading anuncia "Carregando". Mantenha o texto original do botão.
• Alternância: use aria-pressed="true" ou "false".
• Abre um painel: use aria-expanded e aria-controls com o id do painel.
• Abre menu ou diálogo: use aria-haspopup, por exemplo aria-haspopup="dialog".

Não use tabindex positivo. As animações respeitam a preferência do sistema por menos movimento.

Eventos nativos

Ouça click no br-button, como em um <button>. Ele ocorre com mouse, Enter ou Espaço.

document.querySelector('br-button').addEventListener('click', () => salvar());

Com type="submit" ou type="reset", os eventos submit e reset ocorrem no <form>, não no botão. O botão não emite input nem change.

Atributos nativos

O botão participa do formulário como um <button>: aceita type, name, value, disabled e form. Os tipos aceitos são button (padrão), submit e reset.

formaction, formmethod, formenctype, formtarget e formnovalidate não são suportados. Para enviar a outro destino, ajuste o próprio <form>.

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-table-action
• br-table-bar
• br-table-cell
• br-tag
• br-time-picker
• br-tooltip
• br-upload
• br-wizard

Gráfico

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

O texto e o ícone passaram a ficar dentro do botão. A aparência usa emphasis e shape.

1.x	2.x	O que fazer
block / circle	shape	Use shape="block" ou shape="circle".
icon	br-icon dentro do botão	Coloque o ícone no conteúdo, com src, svg ou o slot do br-icon.
inverted	color-mode	Renomeie.
label	conteúdo do botão	Coloque o texto dentro do elemento.
loading	loading	Mantenha.
submit	type="submit"	Use o tipo nativo.
type (aparência)	emphasis	Use emphasis. O type agora é o tipo nativo: button, submit ou reset.

1.x:

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

2.x:

<br-button emphasis="primary" type="submit">
  <br-icon src="/icones/check.svg"></br-icon>
  Salvar
</br-button>