Menu

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-menu organiza a navegação lateral da aplicação em gaveta retrátil ou barra fixa.

Use is-open para controlar a visibilidade, ou chame os métodos open(), close() e toggle(). Estruture a navegação com os subcomponentes br-menu-header, br-menu-group, br-menu-list e br-menu-item.

<br-menu id="menu-principal">
  <div slot="header">
    <br-menu-header title-text="Menu Principal"></br-menu-header>
  </div>
  <br-menu-list>
    <br-menu-item>
      <br-menu-link href="/inicio">Início</br-menu-link>
    </br-menu-item>
    <br-menu-item>
      <br-menu-link href="/servicos">Serviços</br-menu-link>
    </br-menu-item>
  </br-menu-list>
</br-menu>

Quando usar

• Menus com hierarquia de seções, grupos ou múltiplos níveis de páginas.
• Navegação lateral que precisa ser recolhida em telas móveis com fechamento por máscara (br-scrim).

Quando evitar

• Poucos itens que cabem diretamente no cabeçalho: use br-header.
• Alternar visões na mesma página: use br-tab.

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

Como controlar a abertura do menu

Para abrir, fechar ou alternar o menu via JavaScript, use os métodos open(), close() ou toggle(), ou alterne a propriedade isOpen. O evento brMenuOpenChange é emitido sempre que o estado muda.

Associação com o cabeçalho

Para acionar o menu a partir de um botão no br-header, aponte data-target para o id do menu:

<br-header>
  <button slot="menu-trigger" data-toggle="menu" data-target="#menu-principal" aria-expanded="false">
    Menu
  </button>
</br-header>
<br-menu id="menu-principal"></br-menu>

Sobreposição e dimensões

No modo sobreposto, o menu abre como diálogo modal sobre o conteúdo da página. Quando o navegador suporta showModal(), ele entra na top layer.

Nos modos push, fixed e contextual, o menu permanece no fluxo normal da página.

• Largura no modo fixed: usa 20rem por padrão. Para alterar, defina a variável CSS --menu-fixed-width no br-menu.
• Largura no modo sobreposto: a propriedade breakpoints aceita classes de grade GovBR (ex.: col-sm-4 col-lg-3). Sem essas classes, o painel ocupa a largura padrão disponível.

Propriedades

breakpoints

Atributo	breakpoints
Descrição	Classes de coluna do grid GovBR para definir a largura responsiva do painel sobreposto. Exemplo: col-sm-4 col-lg-3. Os modos push, fixed e contextual não usam esta propriedade. Quando vazia, o painel ocupa a largura disponível.
Tipo	string
Valor padrão	''

contextual

Atributo	contextual
Descrição	Define se o menu deve usar comportamento contextual (aparece na parte inferior). Quando ativado, o menu é posicionado na parte inferior da tela em dispositivos móveis.
Tipo	boolean
Valor padrão	false

contextualLabel

Atributo	contextual-label
Descrição	Rótulo do botão trigger do menu contextual. Exibido apenas em modo contextual e em telas menores (mobile).
Tipo	string
Valor padrão	'Menu Contextual'

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()

density

Atributo	density
Descrição	Define a densidade dos itens do menu, alterando o espaçamento interno. - small (densidade alta): itens mais compactos - medium (padrão): equilíbrio entre economia de espaço e separação - large (densidade baixa): maior espaçamento (recomendado em touch) Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

fixed

Atributo	fixed
Descrição	Mantém o menu como uma barra lateral fixa quando estiver aberto. O menu continua podendo ser ocultado alterando isOpen ou chamando close(). A largura padrão é 20rem, limitada à viewport, e pode ser sobrescrita pela variável CSS --menu-fixed-width.
Tipo	boolean
Valor padrão	false

isOpen

Atributo	is-open
Descrição	Define se o painel do menu está aberto/visível. Em modo push, esta propriedade permite controle externo da visibilidade. O nome permanece porque o método público open() já ocupa a propriedade open no host.
Tipo	boolean
Valor padrão	false

push

Atributo	push
Descrição	Define se o menu deve usar comportamento push. Quando ativado, o menu permanece fixo na lateral e empurra o conteúdo principal.
Tipo	boolean
Valor padrão	false

socialTitle

Atributo	social-title
Descrição	Título da seção de redes sociais exibida no rodapé do menu. Utilize esta propriedade para personalizar o texto que aparece acima dos ícones sociais.
Tipo	string
Valor padrão	'Redes Sociais'

Slots

Nome	Descrição
"default"	Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).
"header"	Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push.
"info"	Slot para informações adicionais no rodapé.
"link"	Slot para links externos no rodapé (use br-menu-link).
"logo"	Slot para logotipos de parceiros no rodapé.
"social"	Slot para ícones de redes sociais no rodapé.

Eventos

Evento	Descrição	Depreciação	Propagação
brMenuOpenChange	Evento emitido quando o menu abre ou fecha. detail.open contém o estado concluído e detail.sourceId identifica a instância pelo id ou customId.	---	true
brMenuStateChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando o menu abre ou fecha.	Use brMenuOpenChange.	true

Métodos

close

Descrição	Fecha o painel do menu. Pode ser chamado externamente: menuEl.close().
Assinatura	close() => Promise<void>
Parâmetros	---

open

Descrição	Abre o painel do menu. Pode ser chamado externamente: menuEl.open().
Assinatura	open() => Promise<void>
Parâmetros	---

toggle

Descrição	Alterna o estado do painel do menu (abre se fechado, fecha se aberto). Pode ser chamado externamente: menuEl.toggle().
Assinatura	toggle() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"back-btn"	Botão de voltar do menu de navegação drill-down.
"body"	Parte principal onde ficam os links e grupos de navegação.
"container"	Parte para o container externo que envolve o menu inteiro.
"footer"	Parte para o contêiner principal do rodapé do menu, agrupando logos, links, redes sociais e informações.
"info"	Parte para informações adicionais, como licença ou direitos autorais.
"link"	Parte para links úteis ou navegação secundária no rodapé.
"logo"	Parte para a área de logotipos de parceiros no rodapé.
"panel"	Parte para o painel de navegação do menu (o menu propriamente dito).
"social"	Parte para ícones de redes sociais no rodapé.
"trigger"	Botão de acionamento do menu (hambúrguer ou contextual).

Acessibilidade

O painel do menu recebe role="dialog" quando é uma sobreposição (contextual/push) e role="navigation" quando é persistente. O botão de acionamento reflete aria-expanded.

Foco

• Enquanto aberto como sobreposição, o foco fica preso no painel: Tab e Shift+Tab circulam entre os elementos focáveis internos.
• Ao abrir, o foco vai para o primeiro item; ao fechar, volta para o acionador.
• Na navegação drill-down, o botão "voltar" (::part(back-btn)) e a pilha de navegação mantêm a orientação; ao voltar um nível o foco é reposicionado.

Teclado

• ArrowDown/ArrowUp movem o foco entre os itens de navegação (roving).
• Escape fecha o menu no nível raiz; dentro de um submenu, Escape, ArrowLeft e Backspace voltam um nível.
• No menu contextual, Enter/Espaço no acionador abrem o menu.
• Clique no scrim (fundo) ou fora do painel fecha o menu.

Estrutura

Use br-menu-list, br-menu-group e br-menu-item para a hierarquia. O item da rota atual deve indicar o estado ativo; passe aria-current="page" no item correspondente quando o menu refletir a navegação da aplicação.

Movimento

Abertura, fechamento e o drill-down respeitam prefers-reduced-motion: reduce.

Dependências

Subcomponentes

• br-menu-group
• br-menu-header
• br-menu-info
• br-menu-item
• br-menu-link
• br-menu-list
• br-menu-logo
• br-menu-social

Depende de

• br-scrim
• br-button
• br-icon

Gráfico

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

Na 1.x, o menu recebia grande parte da árvore de navegação em objetos pela propriedade list. Na 2.x, o menu é um contêiner e a árvore deve ser declarada com br-menu-list e br-menu-item.

Propriedades e composição

API 1.x	API 2.x	Ação na migração
dataBreakpoints	breakpoints	Renomeie e revise o formato.
density, contextualLabel, socialTitle	mesmos nomes	Mantenha quando usados.
isContextual	contextual	Renomeie.
isPush	push	Renomeie.
list	br-menu-list / br-menu-item	Troque o objeto de dados por composição de elementos.
logoHeader, links, social, info	slots/subcomponentes	Distribua cada parte na área semântica correspondente.
showMenu	isOpen	Renomeie e controle o estado aberto.

Para aplicações SPA, configure navigation-mode nos itens e trate brNavigate no nível da aplicação.

Exemplo

1.x:

<br-menu :list="items" :is-push="true"></br-menu>

2.x:

<br-menu push>
  <br-menu-list>
    <br-menu-item href="/inicio">Início</br-menu-item>
    <br-menu-item href="/servicos">Serviços</br-menu-item>
  </br-menu-list>
</br-menu>