Breadcrumb

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-breadcrumb mostra o caminho até a página atual e permite voltar aos níveis anteriores.

Como montar

1. Declare um br-breadcrumb-item para cada nível, do início até a página atual.
2. Use home no primeiro item para exibir o ícone de página inicial.
3. Marque a página atual com active: ela aparece sem link e com aria-current="page".

<br-breadcrumb>
  <br-breadcrumb-item home label="Início" href="/"></br-breadcrumb-item>
  <br-breadcrumb-item label="Serviços" href="/servicos"></br-breadcrumb-item>
  <br-breadcrumb-item label="Emitir documento" active></br-breadcrumb-item>
</br-breadcrumb>

Os mesmos itens podem ser passados em crumbs, como array ou texto JSON. Quando falta espaço, os níveis intermediários são agrupados; truncate-after define a partir de quantos itens isso acontece.

Navegação em SPA

Com navigation-mode="event", o clique em um item emite brNavigate. Cancele o evento e passe o endereço para o roteador:

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

Quando usar

• Páginas com dois ou mais níveis de hierarquia.

Quando evitar

• Navegação sem hierarquia.
• Etapas de um processo: use br-wizard ou br-step.

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

crumbs

Atributo	crumbs
Descrição	Fornece os nomes e links do breadcrumb. Use uma string JSON no atributo HTML ou um array de BreadcrumbItem por property binding. Cada item deve ter label string e pode ter href, target, home e active. Itens inválidos são ignorados; se nenhum item válido restar, usa defaultCrumbs e avisa no console. (obrigatório)
Exemplo de uso	<br-breadcrumb crumbs='[{"label":"Início","href":"/"},{"label":"Serviço","active":true}]' ></br-breadcrumb> const breadcrumb = document.querySelector('br-breadcrumb'); breadcrumb.crumbs = [ { label: 'Início', href: '/' }, { label: 'Serviço', active: true }, ];
Tipo	BreadcrumbItem[] | string
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()

homeHref

Atributo	home-href
Descrição	URL padrão da página inicial. Quando informada, tem precedência sobre homeUrl.
Tipo	string
Valor padrão	---

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

Atributo	home-url
Depreciação	Use homeHref.
Descrição	Caso não seja fornecido, o valor padrão será /.
Tipo	string
Valor padrão	'/'

navigationMode

Atributo	navigation-mode
Descrição	Controla como os links do breadcrumb integram a navegação mantendo href real nos itens navegáveis. - 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. Valores inválidos usam native.
Tipo	"event" | "native"
Valor padrão	'native'

truncateAfter

Atributo	truncate-after
Descrição	Quantidade máxima de crumbs exibidos antes de ativar o modo truncado. Quando omitida, o truncamento continua sendo decidido apenas pelo espaço disponível. Valores inválidos são ignorados.
Tipo	number
Valor padrão	---

Slots

Nome	Descrição
"default"	Itens de breadcrumb declarados via elementos br-breadcrumb-item. O elemento br-crumb é aceito apenas por compatibilidade.

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

CSS Shadow Parts

Nome	Descrição
"list"	Lista ordenada de itens do breadcrumb.
"nav"	Elemento nav do breadcrumb.

Migração da navegação

Nos itens, troque url por href. Para a SPA controlar a navegação, troque is-spa-link-behavior por navigation-mode="event" e trate o evento brNavigate.

<!-- Antes -->
<br-breadcrumb is-spa-link-behavior crumbs='[{"label":"Serviços","url":"/servicos"},{"label":"Atual","active":true}]'></br-breadcrumb>

<!-- Agora -->
<br-breadcrumb navigation-mode="event" crumbs='[{"label":"Serviços","href":"/servicos"},{"label":"Atual","active":true}]'></br-breadcrumb>

O destino do item inicial passou a ser home-href; home-url ainda funciona, mas está depreciado. Com navigation-mode="event", o item inicial também emite brNavigate.

Dependências

Subcomponentes

• br-breadcrumb-item
• br-crumb

Depende de

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

Gráfico

Migração de <br-breadcrumb> (1.x → 2.x)

1.x	2.x	O que fazer
—	home-href	Destino do item inicial.
—	navigation-mode	Use event quando a SPA controlar a navegação.
label	aria-label	Use para nomear a navegação para leitores de tela.
links	crumbs ou br-breadcrumb-item	Renomeie e revise o formato dos itens: label, href, home e active.

1.x:

<br-breadcrumb :links="links" label="Você está em"></br-breadcrumb>

2.x:

<br-breadcrumb :crumbs="crumbs" home-href="/" aria-label="Você está em"></br-breadcrumb>