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 componente br-dropdown é o painel flutuante de sobreposição do GovBR-DS, ativado por um controle gatilho para apresentar listas contextuais de comandos, opções ou conteúdos complementares.

Para que serve

• Menus de contexto e ações: Agrupa múltiplas ações secundárias ou suplementares que não precisam ficar expostas permanentemente na interface (ex.: menu "Mais opções", "Exportar", "Filtrar por").
• Posicionamento flutuante inteligente: Gerencia a exibição da superfície suspensa sobre o conteúdo da página, garantindo contraste, elevação e fechamento ao clicar fora (click outside) ou pressionar a tecla Escape.
• Comportamento acessível: Associa o elemento acionador ao painel de destino via atributos WAI-ARIA (aria-expanded, aria-haspopup).

Quando utilizar

• Utilize quando:
  • O espaço na barra de ferramentas ou cabeçalho for limitado e houver várias ações pontuais a serem oferecidas.
  • For necessário apresentar uma lista suspensa de comandos acionáveis.
• Evite e prefira outro componente quando:
  • O objetivo for permitir a seleção de valor para submissão em formulário (prefira br-select).
  • O conteúdo for a estrutura principal de navegação do site (prefira br-menu).
  • A mensagem for uma notificação assíncrona ou alerta (prefira br-message ou br-notification).

Estrutura e Slots

O br-dropdown é composto por duas regiões fundamentais:

• trigger: Slot obrigatório onde a aplicação declara o botão ou link de acionamento (como um br-button).
• target: Slot onde a aplicação declara o painel, lista de itens ou conteúdo flutuante exibido ao abrir o dropdown.

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

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.

Quando matchTriggerWidth está ativo, a largura do painel é recalculada junto com o posicionamento e acompanha o acionador. O comportamento é opt-in; por padrão, o conteúdo continua determinando a largura.

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

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 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.

Acessibilidade

O br-dropdown associa o acionador ao painel: o elemento do slot trigger recebe aria-controls, aria-expanded (sincronizado com is-open) e aria-haspopup="true". Se o slot já contém um controle interativo (button, a[href], input…), ele é o acionador semântico; caso contrário, o wrapper do trigger recebe tabindex="0".

Teclado e foco

• Enter/Espaço no acionador abre/fecha.
• ArrowDown com o painel aberto move o foco para o primeiro elemento focável do conteúdo.
• Escape fecha e devolve o foco ao acionador.
• Clique fora fecha, a menos que prevent-auto-dismiss esteja ativo.
• disabled remove o acionador da tabulação e marca aria-disabled.

Uso

• Defina aria-label no br-dropdown quando o acionador não tiver texto visível.
• O painel usa a camada --z-index-layer-1; se ele empatar com um preview/iframe do consumidor, ajuste a camada no ancestral responsável, não com z-index arbitrário.

Movimento

Abertura e fechamento do painel respeitam prefers-reduced-motion: reduce.

Dependências

Usado por

• br-pagination

Depende de

• br-icon

Gráfico