Menu
Visão Geral
O componente br-menu é o orquestrador completo de navegação lateral (drawer/sidebar) do GovBR-DS. Estrutura a navegação multinível de portais e sistemas públicos, oferecendo suporte a hierarquias em árvore, agrupamentos, busca interna, informações do usuário e canais sociais.
Para que serve
- Navegação estruturada em árvore: Permite navegar por hierarquias profundas de seções e subsistemas governamentais.
- Modos responsivos: Suporta exibição fixa/lateral no desktop e painel retrátil suspenso com cortina de fundo (
br-scrim) em telas mobile. - Acessibilidade completa: Gerencia controle de foco por teclado, armadilha de foco (trap focus) quando aberto e atributos WAI-ARIA (
aria-expanded,role="dialog"ourole="navigation"). - Navegação multinível fluida: Oferece transições suaves entre níveis hierárquicos com botões de retorno ao nível anterior.
Quando utilizar
- Utilize quando:
- A aplicação ou portal exigir uma estrutura de navegação lateral abrangente, com menus de múltiplos níveis e categorias.
- Houver necessidade de um menu que possa ser recolhido ou deslizado em dispositivos móveis com controle de foco integrado.
- Evite e prefira outro componente quando:
- A navegação tiver poucos itens e puder ser acomodada confortavelmente apenas no cabeçalho (prefira
br-header). - O objetivo for alternar visualizações na mesma tela de forma plana (prefira
br-tab).
- A navegação tiver poucos itens e puder ser acomodada confortavelmente apenas no cabeçalho (prefira
Composição e Subcomponentes
| Subcomponente | Papel | Regra de uso |
|---|---|---|
br-menu-group | Agrupador temático. Agrupa itens sob um subtítulo de seção. | Inserido no corpo de navegação do br-menu. |
br-menu-header | Cabeçalho do menu. Exibe título e botão de fechar o painel. | Inserido no topo do br-menu. |
br-menu-info | Informações de apoio. Exibe dados de sessão, versão ou contexto do sistema. | Posicionado na base ou topo do br-menu. |
br-menu-item | Item de menu. Opção clicável de rota ou gatilho para submenu. | Deve ser utilizado dentro de um br-menu-list. |
br-menu-link | Hiperlink. Link textual padronizado no menu. | Inserido dentro de br-menu-item ou seções de apoio. |
br-menu-list | Lista de opções. Estrutura semântica de lista contendo itens navegáveis. | Inserido no br-menu ou dentro de um br-menu-group. |
br-menu-logo | Logotipo. Exibe a marca do órgão no interior do menu. | Posicionado no cabeçalho ou topo do br-menu. |
br-menu-social | Redes sociais. Bloco de canais sociais oficiais no menu. | Posicionado preferencialmente no rodapé do br-menu. |
br-menu | Orquestrador principal. Gerencia estado aberto/fechado, navegação multinível, scrim e armadilha de foco. | Deve ser declarado como contêiner principal da navegação lateral. |
Como os subcomponentes se relacionam
O br-menu atua como o orquestrador soberano da navegação. Ele controla a transição de visibilidade, a ativação do scrim de fundo e o comportamento dos subníveis. Ao navegar entre níveis, os itens (br-menu-item) comunicam suas seleções ao br-menu, que desliza os painéis correspondentes e mantém a ordem correta de tabulação do teclado.
Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.
Exemplo(s)
Estado aberto e associação com header
isOpen é a fonte de verdade pública do menu. Interação, open(), close() e
toggle() atualizam essa propriedade e emitem brMenuOpenChange uma vez, com
detail.open e detail.sourceId. Escrita com o mesmo valor não emite evento.
Ao usar um trigger no br-header, defina data-target com o id ou customId
do menu. Isso isola páginas com vários headers e menus e mantém aria-expanded
sincronizado somente no trigger associado.
<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>
Fluxo, camada e modalidade
O menu sobreposto usa um <dialog> modal e a top layer quando showModal() está disponível. O painel e a máscara
compartilham o mesmo contexto: máscara na subcamada local 0 e painel na 1. Sem suporte nativo, o conjunto permanece
fixed na camada de navegação temporária 3.
Os modos push, fixed e contextual não entram na top layer e mantêm o comportamento local ou persistente. No
fallback CSS, mantenha apenas um bloqueador legado ativo por vez.
No modo fixed, o painel usa 20rem como largura padrão, limitada à viewport.
Defina --menu-fixed-width no br-menu para personalizar esse valor.
No modo sobreposto, breakpoints aceita classes de coluna do grid GovBR, como
col-sm-4 col-lg-3. Sem essas classes, o painel ocupa a largura disponível. Os
modos push, fixed e contextual mantêm suas próprias regras de largura.
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 sobrescritapela 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 canônico 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 | 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:
TabeShift+Tabcirculam 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/ArrowUpmovem o foco entre os itens de navegação (roving).Escapefecha o menu no nível raiz; dentro de um submenu,Escape,ArrowLefteBackspacevoltam um nível.- No menu contextual,
Enter/Espaçono 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
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>
