Dropdown

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-dropdown abre um painel flutuante a partir de um botão, com ações ou conteúdo complementar, como um menu "Mais opções".

Coloque o botão no slot trigger e o conteúdo no slot target:

<br-dropdown>
  <br-button slot="trigger" emphasis="tertiary">Mais opções</br-button>
  <br-list slot="target">
    <br-item>Exportar</br-item>
    <br-item>Imprimir</br-item>
  </br-list>
</br-dropdown>

O painel fecha com Escape ou com um clique fora dele (desative com prevent-auto-dismiss). A posição é definida por placement, por exemplo bottom-start ou top-end. Para acompanhar a abertura e o fechamento, ouça brDropdownOpenChange.

Quando usar

• Várias ações secundárias quando há pouco espaço na tela.

Quando evitar

• Escolher um valor de formulário: use br-select.
• Navegação principal do site: use br-menu.
• Avisos: use br-message ou br-notification.

Consulte as diretrizes de design do GovBR.

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

Sobreposição

O painel flutua sobre o conteúdo: abrir ou fechar não empurra o restante da página. Por padrão, a largura acompanha o conteúdo; com match-trigger-width, fica igual à do botão.

Se o painel ficar atrás de outro elemento, ajuste target-z-index. Quando um modal, o cookiebar ou o menu sobreposto abre, o dropdown fecha, a menos que esteja dentro deles.

Propriedades

ariaLabel

Atributo	aria-label
Descrição	Define o rótulo acessível usado por tecnologias assistivas. > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam ariaLabel.
Tipo	string
Valor padrão	---

arrowPosition

Atributo	arrow-position
Descrição	Define o posicionamento da seta ('left' ou 'right') em relação ao elemento acionador. O valor padrão é 'right'.
Tipo	"left" | "right"
Valor padrão	'right'

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId(). > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam customId.
Tipo	string
Valor padrão	generateUniqueId()

disabled

Atributo	disabled
Descrição	Desabilita a interação com o componente. > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam disabled.
Tipo	boolean
Valor padrão	false

isOpen

Atributo	is-open
Descrição	Indica se o dropdown está aberto ou fechado. Esta propriedade é refletida no DOM e pode ser alterada externamente. O valor padrão é falso (fechado).
Tipo	boolean
Valor padrão	false

matchTriggerWidth

Atributo	match-trigger-width
Descrição	Faz o painel acompanhar a largura do acionador enquanto estiver aberto. O valor padrão false preserva a largura determinada pelo conteúdo.
Tipo	boolean
Valor padrão	false

placement

Atributo	placement
Descrição	Define o posicionamento do target (alvo) em relação ao trigger (acionador).
Tipo	"bottom" | "bottom-end" | "bottom-start" | "left" | "right" | "top" | "top-end" | "top-start"
Valor padrão	'bottom-start'

preventAutoDismiss

Atributo	prevent-auto-dismiss
Descrição	Define se o dropdown deve permanecer aberto quando outro dropdown é aberto. Quando definido como false (padrão), o dropdown será fechado automaticamente quando outro dropdown for aberto. Quando definido como true, o dropdown permanecerá aberto mesmo quando outro dropdown for aberto.
Tipo	boolean
Valor padrão	false

showArrow

Atributo	show-arrow
Descrição	Exibe uma seta ao lado do elemento acionador. O valor padrão é falso para preservar a apresentação dos triggers existentes.
Tipo	boolean
Valor padrão	false

targetZIndex

Atributo	target-z-index
Descrição	Define o z-index do elemento target (alvo) do dropdown. Permite customizar a ordem de sobreposição do painel dropdown em relação aos demais elementos da página. O valor padrão utiliza a variável CSS do design system: var(--z-index-layer-1).
Tipo	string
Valor padrão	'var(--z-index-layer-1)'

Slots

Nome	Descrição
"target"	Slot para o conteúdo exibido pelo dropdown.
"trigger"	Slot para o elemento que aciona a abertura do dropdown.

Eventos

Evento	Descrição	Depreciação	Propagação
brDidClose	Emitido quando o dropdown fecha.	---	true
brDidOpen	Emitido quando o dropdown abre.	---	true
brDropdownChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brDropdownOpenChange.	true
brDropdownOpenChange	Evento emitido quando o estado aberto muda.	---	true

Métodos

close

Descrição	Fecha o dropdown e mantém o formato de retorno legado.
Assinatura	close() => Promise<{ isOpen: boolean; }>
Parâmetros	---

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

Descrição	Esconde o dropdown. Define a propriedade isOpen como falsa e retorna o novo estado. Este método pode ser chamado externamente.
Assinatura	hide() => Promise<{ isOpen: boolean; }>
Depreciação	Use close.
Parâmetros	---

open

Descrição	Abre o dropdown. Define a propriedade isOpen como verdadeira e retorna o novo estado. Este método pode ser chamado externamente.
Assinatura	open() => Promise<{ isOpen: boolean; }>
Parâmetros	---

setFocus

Descrição	Define o foco no elemento interno do componente. Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.
Assinatura	setFocus() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"target"	Área de conteúdo exibida pelo dropdown.
"trigger-arrow"	Indicador visual opcional do acionador do dropdown.
"trigger"	Área do acionador do dropdown.

Acessibilidade

O botão do slot trigger informa se o painel está aberto (aria-expanded) e qual painel ele controla. Se o botão não tiver texto visível, informe aria-label no br-dropdown.

Teclado

• Enter ou Espaço no botão abre e fecha o painel.
• Seta para baixo, com o painel aberto, leva o foco ao primeiro item.
• Tab e Shift+Tab percorrem os itens do painel.
• Setas, Home e End navegam entre itens que não são links.
• Escape fecha o painel e devolve o foco ao botão.

Ao abrir outro br-dropdown, o painel anterior fecha, inclusive quando os componentes estão dentro do Shadow DOM de uma tabela. Com prevent-auto-dismiss, o painel permanece aberto ao abrir outro dropdown.

Com disabled, o botão sai da ordem de tabulação. A animação respeita a preferência do sistema por menos movimento.

Dependências

Usado por

• br-pagination
• br-table-bar
• br-table-cell

Depende de

• br-icon

Gráfico