Copiar página como Markdown para IA
Header
Visão Geral
O componente br-header é o orquestrador principal de cabeçalho do GovBR-DS. Centraliza a identidade visual do órgão ou sistema público, links de navegação hierárquica, atalhos de funcionalidades, mecanismo de busca e botão de acesso ou autenticação.
Para que serve
- Identidade institucional unificada: Apresenta a marca e assinatura visual oficial do Governo Federal e da entidade pública.
- Navegação e atalhos rápidos: Reúne links para áreas centrais e botões funcionais (como contraste, acessibilidade e suporte).
- Busca e autenticação integradas: Fornece áreas reservadas e slots para barra de busca rápida e gatilho de login/acesso.
- Comportamento responsivo e densidades: Adapta-se automaticamente a diferentes telas com suporte a densidades padrão, compacta, pequena e grande.
Quando utilizar
- Utilize quando:
- Desenvolver páginas, portais e sistemas públicos federais que requerem a barra superior padronizada do GovBR-DS.
- For necessário integrar identidade visual, navegação rápida, busca e acesso em uma estrutura consistente.
- Evite e prefira outro componente quando:
- A navegação for exclusivamente lateral ou contextual interna de uma ferramenta gráfica (prefira
br-menuou barras de ferramentas específicas).
- A navegação for exclusivamente lateral ou contextual interna de uma ferramenta gráfica (prefira
Composição e Subcomponentes
| Subcomponente | Papel | Regra de uso |
|---|---|---|
br-header-function | Ação funcional. Botão de utilidade rápida (contraste, ajuda, etc.). | Deve ser inserido dentro de um br-header-list no slot functions. |
br-header-link | Item de link. Atalho ou hiperlink de navegação institucional. | Deve ser inserido dentro de um br-header-list no slot links. |
br-header-list | Agrupador de lista. Contêiner semântico horizontal para links ou funções. | Encaixa-se nos slots links ou functions do br-header. |
br-header-logo | Identidade visual. Exibe o logotipo ou brasão institucional. | Posicionado nos slots logo ou signature do br-header. |
br-header | Orquestrador principal. Estrutura as áreas superior e inferior, gerencia responsividade e densidade. | Deve ser declarado como elemento raiz do topo da página. |
Como os subcomponentes se relacionam
O br-header orquestra as áreas da barra através de slots nomeados (logo, signature, links, functions, search, access, menu-trigger, caption, subcaption). Ele observa o tamanho de tela e a densidade configurada, reorganizando os blocos e delegando a exibição correta aos subcomponentes filhos.
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
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
Propriedades
caption
| Atributo | caption |
|---|---|
| Descrição | Texto exibido como título do cabeçalho. |
| Tipo | string |
| Valor padrão | null |
captionUrl
| Atributo | caption-url |
|---|---|
| Descrição | URL associada ao título do cabeçalho. |
| Tipo | string |
| Valor padrão | null |
compact
| Atributo | compact |
|---|---|
| Descrição | Estado compacto canônico. Quando informado, tem precedência sobre isCompact. |
| Tipo | boolean |
| Valor padrão | --- |
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 visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento).- medium: Densidade intermediária, padrão recomendado para a maioria dos casos.- large: Baixa densidade (componente maior, mais espaçamento e altura).Valores inválidos usam medium. |
| Tipo | "large" | "medium" | "small" |
| Valor padrão | 'medium' |
isCompact
| Atributo | is-compact |
|---|---|
| Depreciação | Use compact. |
| Descrição | Ativa o modo compacto do cabeçalho. |
| Tipo | boolean |
| Valor padrão | false |
isSticky
| Atributo | is-sticky |
|---|---|
| Depreciação | Use sticky. |
| Descrição | Fixa o cabeçalho no topo durante a rolagem. Quando compact ou is-compact é definido explicitamente, o modo visualpermanece fixo durante a rolagem. Sem essa configuração, o header sticky alterna automaticamente entre os modos compacto e expandido. |
| Tipo | boolean |
| Valor padrão | false |
layoutWidth
| Atributo | layout-width |
|---|---|
| Descrição | Define a largura do container interno do cabeçalho. - contained: largura máxima limitada pela grade no breakpoint desktop (container-lg).- full: sempre ocupa 100% da largura disponível (container-fluid). |
| Tipo | "contained" | "full" |
| Valor padrão | 'contained' |
navigationMode
| Atributo | navigation-mode |
|---|---|
| Descrição | Controla como os links internos do cabeçalho integram a navegação mantendo href real.- native (padrão): preserva o comportamento do navegador, conforme HTML/W3C.- event: emite brNavigate; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir. |
| Tipo | "event" | "native" |
| Valor padrão | 'native' |
shrinkFirst
| Atributo | shrink-first |
|---|---|
| Descrição | Define qual lista encolhe primeiro quando o espaço é limitado. |
| Tipo | "functions" | "links" |
| Valor padrão | 'functions' |
signature
| Atributo | signature |
|---|---|
| Descrição | Texto da assinatura exibida ao lado da logo. |
| Tipo | string |
| Valor padrão | null |
sticky
| Atributo | sticky |
|---|---|
| Descrição | Fixa o cabeçalho no topo. Quando informado, tem precedência sobre isSticky. |
| Tipo | boolean |
| Valor padrão | --- |
subcaption
| Atributo | subcaption |
|---|---|
| Descrição | Texto exibido como subtítulo do cabeçalho. |
| Tipo | string |
| Valor padrão | null |
subcaptionUrl
| Atributo | subcaption-url |
|---|---|
| Descrição | URL associada ao subtítulo do cabeçalho. |
| Tipo | string |
| Valor padrão | null |
Slots
| Nome | Descrição |
|---|---|
"access" | Slot para o botão de acesso ou autenticação. |
"caption" | Slot para o título do cabeçalho. |
"functions" | Slot para botões de ação no cabeçalho. |
"links" | Slot para links de navegação principais. |
"logo" | Slot para a logo do cabeçalho. |
"menu-trigger" | Slot para o botão que abre o menu. |
"search" | Slot para o campo de busca. |
"signature" | Slot para a assinatura visual da organização. |
"subcaption" | Slot para o subtítulo do cabeçalho. |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
brHeaderCompactChange | Evento canônico emitido quando o modo compacto muda. | --- | true |
brMenuToggle | Evento disparado para alternar o estado de um menu associado. | --- | true |
brNavigate | Evento cancelável emitido em navigation-mode="event" para cliques primários sem modificadores em links _self. Chame event.preventDefault() no listener para impedir a navegação nativa e entregar event.detail.href ao roteador da SPA. | --- | true |
headerCompactChange | Evento disparado quando o cabeçalho entra ou sai do modo compacto. O evento contém os detalhes do estado compacto e o ID do componente pai. | --- | true |
headerWidthChange | Evento disparado para indicar qual lista deve encolher primeiro. O evento contém os detalhes do ID do componente pai e o nome da lista. | --- | true |
Métodos
resetHeaderList
| Descrição | Reinicializa o estado das listas do cabeçalho, disparando o evento de redimensionamento. Pode ser chamado externamente para forçar a atualização das listas. |
|---|---|
| Assinatura | resetHeaderList() => Promise<void> |
| Parâmetros | --- |
CSS Shadow Parts
| Nome | Descrição |
|---|---|
"bottom-left" | Área inferior esquerda (menu + título). |
"bottom-right" | Área inferior direita (busca expandida). |
"bottom" | Área inferior do header. |
"header" | Elemento header principal. |
"top-left" | Área superior esquerda (logo + assinatura). |
"top-right" | Área superior direita (links + funções + busca + acesso). |
"top" | Área superior do header. |
Acessibilidade
O br-header renderiza um landmark <header> (::part(header)) e organiza o
conteúdo por slots nomeados (logo, signature, links, functions,
search, access, menu-trigger, caption, subcaption). O nome/título vem
de caption (com link opcional por caption-url).
Navegação e menu
- Coloque os links principais no slot
links(viabr-header-link, que renderiza âncoras reais). Marque o link da rota atual comaria-current="page". - O botão no slot
menu-triggertem seuaria-expandedsincronizado com o estado de abertura dobr-menuassociado (eventobrMenuOpenChange). - A navegação por teclado segue a ordem natural dos controles projetados; o componente reposiciona o foco na lista de links quando ela muda de layout (compacto ↔ expandido).
Uso
captiondeve ser significativo — é o rótulo do cabeçalho.- Botões só com ícone nos slots
functions/accessprecisam dearia-label. - Em modo
sticky/compact, garanta que o conteúdo da página tenhascroll-padding-topsuficiente para as âncoras não ficarem atrás do header.
Movimento
A reorganização entre layouts e o encolhimento (shrink-first) respeitam
prefers-reduced-motion: reduce.
Migração de Navegação
Antes, os links de caption-url e subcaption-url navegavam diretamente pelo navegador.
Agora, br-header aceita navigation-mode="event" e emite brNavigate para esses links.
<!-- Antes -->
<br-header caption="Portal" caption-url="/portal"></br-header>
<!-- Agora -->
<br-header caption="Portal" caption-url="/portal" navigation-mode="event"></br-header>
As propriedades caption-url e subcaption-url continuam com o mesmo nome. O que mudou foi o suporte ao contrato central de navegação.
Dependências
Subcomponentes
Depende de
Gráfico
Migração de <br-header> (1.x → 2.x)
O header da 1.x concentrava logo, título, busca e ações em propriedades de dados. Na 2.x, a estrutura é composta por slots e subcomponentes, o que permite preservar a semântica e a interação de cada área.
Propriedades e composição
| API 1.x | API 2.x | Ação na migração |
|---|---|---|
actionSearch e dados da busca | slot de busca | Mova o campo e sua ação para o slot correspondente. |
compact | compact | Mantenha; is-compact é apenas alias legado. |
containerFluid | layout-width | Use a configuração de largura atual. |
hasMenu / hasSearch | slots e subcomponentes | Remova as flags e declare menu/busca explicitamente. |
image / imageLink | logo slot / br-header-logo | Mova a marca para a composição de logo. |
isSticky | sticky | Use a propriedade canônica atual. |
signature | signature | Mantenha quando aplicável. |
subtitle | subcaption | Renomeie a propriedade. |
title | caption | Renomeie a propriedade. |
titleLinkUrl | captionUrl | Renomeie a propriedade. |
Exemplo
1.x:
<br-header title="Portal" subtitle="Serviços" image="/logo.svg" has-search></br-header>
2.x:
<br-header caption="Portal" subcaption="Serviços" layout-width="fluid">
<br-header-logo slot="logo" src="/logo.svg"></br-header-logo>
<br-input slot="search" label="Buscar"></br-input>
</br-header>
