Header

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

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Acionamento de Menu Associado

Para integrar o cabeçalho com um menu (br-menu), passe um botão no slot menu-trigger com os seguintes atributos:

• data-toggle="menu"
• data-target="#id-do-menu" (substitua pelo ID ou customId do seu br-menu)

O componente br-menu escuta a esses atributos no escopo do documento e controlará automaticamente sua visibilidade.

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

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).
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

isCompact Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-compact
Depreciação	Use compact.
Descrição	Ativa o modo compacto do cabeçalho.
Tipo	boolean
Valor padrão	false

isSticky Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-sticky
Depreciação	Use sticky.
Descrição	Fixa o cabeçalho no topo durante a rolagem.
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.

Dependências

Subcomponentes

• br-header-function
• br-header-link
• br-header-list
• br-header-logo

Depende de

• br-divider
• br-button
• br-icon

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>

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.