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

Design System

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

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

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

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

Dependências

Usado por

• br-menu-item

Gráfico

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.

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.