Link

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 componente br-link é o controle oficial de hiperlink do GovBR-DS, projetado para orientar e conduzir a pessoa usuária em navegações internas entre páginas ou encaminhamentos para destinos externos.

Para que serve

• Navegação estruturada: Conduz o usuário para novas URLs, rotas de aplicação, âncoras dentro da mesma página ou arquivos para download.
• Identificação de links externos: Permite sinalizar visualmente que o link aponta para um domínio externo ou abre em nova aba/janela, adicionando os atributos de segurança e acessibilidade necessários (target="_blank", rel="noopener noreferrer").
• Estilos inline e de bloco: Adapta-se ao fluxo de leitura textual em parágrafos ou como elemento de navegação isolado com suporte a ícones.

Quando utilizar

• Utilize quando:
  • A ação resultar na alteração da URL do navegador, navegação para outra página ou download de arquivo.
• Evite e prefira outro componente quando:
  • A ação disparar um comportamento na interface sem alterar a URL (como abrir modal, submeter formulário ou acionar filtro): prefira br-button.

Estrutura e Slots

O br-link é um componente autônomo:

• default: Slot para o texto do link, ícones auxiliares ou elementos combinados.

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

Padrão

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

ariaCurrent

Atributo	aria-current
Descrição	Valor canônico de aria-current.
Tipo	string
Valor padrão	null

ariaDescribedBy

Atributo	aria-describedby
Descrição	Valor canônico de aria-describedby.
Tipo	string
Valor padrão	null

ariaExpanded

Atributo	aria-expanded
Descrição	Valor canônico de aria-expanded.
Tipo	string
Valor padrão	null

ariaHasPopup

Atributo	aria-haspopup
Descrição	Valor canônico de aria-haspopup.
Tipo	string
Valor padrão	null

ariaLabel

Atributo	aria-label
Descrição	Valor canônico de aria-label.
Tipo	string
Valor padrão	null

ariaSelected

Atributo	aria-selected
Descrição	Valor canônico de aria-selected.
Tipo	string
Valor padrão	null

button

Atributo	button
Descrição	Exibe o link com o mesmo visual do componente br-button.
Tipo	boolean
Valor padrão	false

disabled

Atributo	disabled
Descrição	Desativa o link, tornando-o não interativo. Quando true: remove o href (um <a> sem href sai da ordem de tabulação e não recebe foco, nem por clique), marca aria-disabled="true" e bloqueia o clique (sem navegação nem emissão de brNavigate). Se o link estiver focado no momento da desativação, o foco é removido. Útil para componentes como br-pagination e br-wizard.
Tipo	boolean
Valor padrão	false

download

Atributo	download
Descrição	Nome sugerido para download. Uma string vazia preserva o nome definido pelo servidor.
Tipo	string
Valor padrão	---

href

Atributo	href
Descrição	URL de destino do link.
Tipo	string
Valor padrão	'#'

hreflang

Atributo	hreflang
Descrição	Idioma do recurso apontado pelo link.
Tipo	string
Valor padrão	---

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

Atributo	is-spa-link-behavior
Depreciação	Use navigationMode="event" e o evento brNavigate.
Descrição	Ativa o comportamento legado de navegação SPA, interceptando cliques simples para atualizar o histórico e emitir brSpaNavigate.
Tipo	boolean
Valor padrão	false

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

Atributo	link-aria-current
Depreciação	Use ariaCurrent.
Descrição	Encaminhamento de aria-current para o elemento âncora interno. Indica o item ativo em um conjunto de navegação (breadcrumb, menu, paginação). Valores comuns: "page" (link da página atual), "step" (etapa ativa), "true". Referência: WCAG 1.3.1 e ARIA aria-current.
Tipo	string
Valor padrão	---

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

Atributo	link-aria-describedby
Depreciação	Use ariaDescribedBy.
Descrição	Encaminhamento de aria-describedby para o elemento âncora interno. Referencia o id de um elemento externo que descreve o link.
Tipo	string
Valor padrão	---

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

Atributo	link-aria-expanded
Depreciação	Use ariaExpanded.
Descrição	Encaminhamento de aria-expanded para o elemento âncora interno.
Tipo	string
Valor padrão	---

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

Atributo	link-aria-haspopup
Depreciação	Use ariaHasPopup.
Descrição	Encaminhamento de aria-haspopup para o elemento âncora interno.
Tipo	string
Valor padrão	---

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

Atributo	link-aria-label
Depreciação	Use ariaLabel.
Descrição	Encaminhamento de aria-label para o elemento âncora interno. Fornece nome acessível ao link quando o conteúdo do slot não é descritivo por si só (ex.: link com ícone sem texto visível).
Tipo	string
Valor padrão	---

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

Atributo	link-aria-selected
Depreciação	Use ariaSelected.
Descrição	Encaminhamento de aria-selected para o elemento âncora interno.
Tipo	string
Valor padrão	---

linkRole

Atributo	link-role
Descrição	Encaminhamento de role para o elemento âncora interno.
Tipo	string
Valor padrão	---

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'

referrerPolicy

Atributo	referrer-policy
Descrição	Política de referrer usada ao buscar o destino.
Tipo	"" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url"
Valor padrão	---

rel

Atributo	rel
Descrição	Relação entre o documento atual e o destino (rel). Quando target="_blank", noopener e noreferrer são sempre incluídos (mesmo que rel seja definido) para mitigar tabnabbing e vazamento de window.opener.
Tipo	string
Valor padrão	---

target

Atributo	target
Descrição	Define como o link será aberto. - _self: abre no mesmo contexto de navegação - _blank: abre em nova aba ou janela - _parent: abre no contexto pai - _top: abre no contexto de nível superior
Tipo	"_blank" | "_parent" | "_self" | "_top"
Valor padrão	---

type

Atributo	type
Descrição	Tipo MIME informativo do recurso apontado.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"default"	Conteúdo do link (texto, ícones ou outros elementos).

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
brSpaNavigate Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brNavigate.	true

CSS Shadow Parts

Nome	Descrição
"anchor"	Parte exposta para o elemento âncora interno, usada para estilos customizados via ::part(anchor).

Migração de Navegação

is-spa-link-behavior e brSpaNavigate continuam disponíveis como aliases depreciados para compatibilidade.

Agora, use navigation-mode="event" e trate brNavigate.

<!-- Antes -->
<br-link href="/perfil" is-spa-link-behavior>Perfil</br-link>

<!-- Agora -->
<br-link href="/perfil" navigation-mode="event">Perfil</br-link>

document.addEventListener('brNavigate', (event) => {
  event.preventDefault();
  router.navigate(event.detail.href);
});

Sem navigation-mode="event", o link usa o modo native e preserva a navegação normal do navegador. Quando navigation-mode="event" e o alias são informados juntos, o modo canônico prevalece.

Eventos nativos

Elemento HTML de referência

br-link encapsula <a href>. O host decora a âncora; navigationMode="event" adiciona navegação coordenada pelo Design System.

Como ouvir os eventos

const link = document.querySelector('br-link');

link.addEventListener('click', (event) => {
  console.log(event.target === link);
});

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
click	ativação da âncora	Sim	Sim	Sim	Sim	Preserva cliques com modificadores e navegação nativa.
focus / blur	entrada ou saída de foco	Não	Sim	Não	Sim	Para delegação, prefira focusin/focusout.

Eventos não aplicáveis ou não suportados

Evento	Situação	Motivo	Alternativa
input / change	Não aplicável	Link não é controle de valor.	Ouça click ou brNavigate.

Eventos customizados do componente

Evento	Quando ocorre	Detail	Bubbles	Composed	Cancelable
brNavigate	clique simples em navigationMode="event"	destino e metadados de navegação	Sim	Sim	Sim
brSpaNavigate	alias depreciado com isSpaLinkBehavior	destino e evento de origem	Sim	Sim	Sim

Valor e estado após o evento

Consulte href, target, rel, download, hreflang, referrerPolicy, type, navigationMode e disabled no host. Cancelar brNavigate impede a ação coordenada.

Frameworks

HTML usa addEventListener; React usa onClick ou ref para brNavigate; Angular usa (click)/(brNavigate); Vue usa @click/@brNavigate.

Acessibilidade

Com href, Enter ativa a âncora. Um link desabilitado perde href e sai da tabulação.

Evidência de teste

_tests/link.e2e.tsx cobre navegação, cancelamento, modificadores, foco e disabled em Chromium headless. A matriz completa de flags e três engines permanece pendente.

Atributos nativos

br-link encaminha href, target, rel, download, hreflang, referrer-policy e type para a âncora interna. target="_blank" mantém noopener noreferrer por segurança.

ping não é suportado porque dispara requisições secundárias de rastreamento. Os atributos de navegação não são copiados automaticamente para componentes compostos que usam links internamente.

Dependências

Usado por

• br-menu-item

Gráfico

Migração para <br-link>

O br-link não existia na linha 1.x. Na 2.x, ele encapsula uma âncora e preserva os recursos nativos de navegação.

<br-link href="/servicos">Serviços</br-link>

Use href, target, rel, download, hreflang, referrer-policy e type como faria em uma âncora. O texto ou conteúdo projetado deve explicar o destino do link.

Para rotas controladas por uma SPA, use navigation-mode="event" e trate o evento cancelável brNavigate. Sem esse modo, a navegação permanece nativa. Cliques com modificadores, botão do meio e destinos diferentes de _self também preservam o comportamento do navegador.

is-spa-link-behavior, brSpaNavigate e as propriedades iniciadas por link-aria- são aliases legados da própria linha 2.x. Eles continuam funcionando por compatibilidade, mas novos códigos devem usar navigationMode, brNavigate e os atributos ARIA canônicos.