Header Function

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.

Subcomponente de Composição

O br-header-function representa uma ação funcional ou atalho utilitário (ex.: contraste, acessibilidade). Deve ser utilizado dentro de um <br-header-list> no slot functions do <br-header>.

Visão Geral

O componente br-header-function é o subcomponente do GovBR-DS que representa uma ação funcional ou utilitária rápida no cabeçalho (como alto contraste, atalhos de acessibilidade, suporte ou configurações).

Para que serve

• Ações utilitárias rápidas: Permite disparar funcionalidades auxiliares com ícone e rótulo sem sair do fluxo da página.
• Feedback interativo: Oferece estados visuais consistentes de foco, hover e ativação.

Papel na composição

Atua como controle interativo de utilidade dentro do cabeçalho.

Regra de uso e relacionamento

• Deve ser utilizado dentro de um br-header-list posicionado no slot functions do br-header.
• Não deve ser utilizado como botão genérico de formulário ou ação primária de conteúdo (para esses casos, utilize br-button).

Propriedades

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

href

Atributo	href
Descrição	URL de destino da funcionalidade.
Tipo	string
Valor padrão	---

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

Atributo	icon-name
Depreciação	Use o slot icon com um SVG, asset ou elemento de ícone controlado pela aplicação.
Descrição	Identificador legado do ícone exibido. Nomes conhecidos são resolvidos pelo registro SVG local; para novos usos, prefira o slot icon com um SVG, asset local ou elemento de ícone controlado pela aplicação.
Tipo	string
Valor padrão	null

navigationMode

Atributo	navigation-mode
Descrição	Controla como o componente integra a navegação mantendo href real no elemento navegável. - 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. Cliques com modificadores, botão do meio ou target diferente de _self permanecem nativos.
Tipo	"event" | "native"
Valor padrão	'native'

target

Atributo	target
Descrição	Define o alvo do link quando href está presente. Pode ser: - _blank para abrir em uma nova aba, - _self para abrir na mesma aba, - _parent para abrir na aba pai, - _top para abrir na aba superior.
Tipo	"_blank" | "_parent" | "_self" | "_top"
Valor padrão	'_self'

Slots

Nome	Descrição
"default"	Slot para o nome ou rótulo da funcionalidade.
"icon"	Slot para ícone que representa a funcionalidade.

Eventos

Evento	Descrição	Depreciação	Propagação
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

Migração de Navegação

Antes, br-header-function encaminhava is-spa-link-behavior para o br-item interno.

Agora, use navigation-mode="event" quando href apontar para uma rota interna da SPA.

<!-- Antes -->
<br-header-function href="/notificacoes" is-spa-link-behavior
  ><i slot="icon" class="fas fa-bell" aria-hidden="true"></i>Notificações</br-header-function
>

<!-- Agora -->
<br-header-function href="/notificacoes" navigation-mode="event"
  ><i slot="icon" class="fas fa-bell" aria-hidden="true"></i>Notificações</br-header-function
>

Quando renderizado como ação sem link, o componente continua se comportando como botão.

Dependências

Componente pai

• br-header

Depende de

• br-button
• br-icon
• br-item

Gráfico