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

O br-header é o cabeçalho da página: logotipo, nome do sistema, links, atalhos, busca, acesso e botão do menu.

Como montar

Cada área tem um slot:

Área	Slot	Componente sugerido
Atalhos (contraste, ajuda…)	functions	br-header-list com br-header-function
Busca	search e search-icon	br-input e um br-button com ícone
Entrar	access	br-sign-in
Links	links	br-header-list com br-header-link
Logotipo	logo	br-header-logo
Menu	menu-trigger	br-button que abre o br-menu
Nome e subtítulo	—	props caption e subcaption

<br-header caption="Nome do sistema" subcaption="Nome do órgão" sticky>
  <br-header-logo slot="logo" src="/logo.svg" description="gov.br"></br-header-logo>

  <br-header-list slot="links" list-title="Acesso rápido">
    <br-header-link href="/servicos">Serviços</br-header-link>
  </br-header-list>

  <br-input slot="search" label="Buscar" type="search"></br-input>

  <br-button slot="menu-trigger" shape="circle" aria-label="Abrir menu" data-toggle="menu" data-target="#menu-principal">
    <br-icon src="/icones/menu.svg"></br-icon>
  </br-button>
</br-header>

Use sticky para manter o cabeçalho visível ao rolar a página e compact para a versão reduzida. Em telas menores, a busca fica escondida até o clique no botão do slot search-icon.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

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

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. 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 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. Quando compact ou is-compact é definido explicitamente, o modo visual permanece 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-icon"	Botão que mostra o campo de busca em telas menores e no modo compacto.
"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 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 header é marcado como cabeçalho da página (<header>). O texto de caption é o nome do cabeçalho: use um nome claro.

• Marque o link da página atual com aria-current="page".
• Botões só com ícone, nos slots functions e access, precisam de aria-label.
• O botão do slot menu-trigger informa se o menu está aberto (aria-expanded), sincronizado com o br-menu.
• Com sticky ou compact, adicione scroll-padding-top na página para que âncoras não fiquem escondidas atrás do cabeçalho.

A reorganização entre os layouts respeita a preferência do sistema por menos movimento.

Migração da navegação

caption-url e subcaption-url continuam com o mesmo nome. Para a SPA controlar esses links, adicione navigation-mode="event" e trate brNavigate.

<br-header caption="Portal" caption-url="/portal" navigation-mode="event"></br-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)

Na 1.x, logo, título, busca e ações eram propriedades. Na 2.x, cada área usa um slot.

1.x	2.x	O que fazer
actionSearch	slot search	Trate a busca no seu campo.
compact	compact	Mantenha. is-compact ainda funciona, mas está depreciado.
containerFluid	layout-width="full"	Renomeie.
hasMenu / hasSearch	slots menu-trigger e search	Declare o botão do menu e o campo de busca.
image / imageLink	br-header-logo no slot logo	Use src e href na logo.
isSticky	sticky	Renomeie.
signature	signature	Mantenha.
subtitle	subcaption	Renomeie.
title	caption	Renomeie.
titleLinkUrl	caption-url	Renomeie.

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">
  <br-header-logo slot="logo" src="/logo.svg" description="Portal"></br-header-logo>
  <br-input slot="search" label="Buscar" type="search"></br-input>
</br-header>