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

Design System

Para a documentação completa de design, 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

Fluxo e sobreposição

O painel do dropdown é uma superfície ancorada fora do fluxo (position: absolute), portanto abrir ou fechar o componente não reserva espaço nem desloca o conteúdo seguinte. No fallback CSS ele usa a camada flutuante 1; o valor público targetZIndex continua podendo sobrescrever essa camada.

Ao abrir um bloqueador externo — scrim, cookiebar modal ou menu sobreposto — o dropdown é fechado. Se estiver contido nesse bloqueador, ele permanece disponível e é posicionado dentro do respectivo contexto de pintura.

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

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 canônico 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.

Dependências

Usado por

• br-pagination

Depende de

• br-icon

Gráfico