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 componente br-breadcrumb é o controle de navegação estrutural do GovBR-DS, desenvolvido para exibir o caminho hierárquico até a página atual e permitir que a pessoa usuária retorne facilmente a níveis anteriores da aplicação.

Para que serve

• Localização contextual: Informa em qual nível da arquitetura de informação o usuário se encontra dentro do portal ou sistema.
• Navegação de retorno: Oferece atalhos diretos para páginas ancestrais sem a necessidade de recorrer repetidamente ao botão "Voltar" do navegador.
• Acessibilidade estruturada WAI-ARIA: Utiliza a semântica nativa de <nav aria-label="Breadcrumb">, identifica a página atual com aria-current="page" e gera separadores visuais acessíveis.

Quando utilizar

• Utilize quando:
  • A aplicação possuir estrutura hierárquica com dois ou mais níveis de profundidade (ex.: Início > Serviços > Cidadão > Solicitar documento).
• Evite e prefira outro componente quando:
  • A aplicação possuir navegação plana (flat) de nível único sem hierarquia.
  • O fluxo for linear com etapas progressivas de um formulário (prefira br-step ou br-wizard).

Composição e Subcomponentes

O ecossistema do Breadcrumb é composto pelo orquestrador e seus itens:

Subcomponente	Papel	Regra de uso
br-breadcrumb-item	Item declarativo canônico. Representa cada nível do caminho hierárquico.	Declarado dentro do slot padrão do br-breadcrumb.
br-breadcrumb	Orquestrador principal. Gerencia a trilha de navegação, insere separadores visuais e controla acessibilidade.	Deve ser o contêiner raiz declarado no template da página.
br-crumb	Item legado de compatibilidade. Equivalente ao br-breadcrumb-item.	Mantido para compatibilidade; prefira br-breadcrumb-item em novos códigos.

Como os subcomponentes se relacionam

O br-breadcrumb atua como container pai que monitora os itens declarados em seu slot padrão:

1. Identificação da página atual: O último item da lista é automaticamente identificado como o destino atual, recebendo destaque visual e aria-current="page" sem link ativo.
2. Separação visual padronizada: O componente pai insere e padroniza os ícones separadores entre os níveis sem poluir a árvore do leitor de tela.

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

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 canônica 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 de Navegação

Antes, os itens declarados em crumbs usavam url e o componente podia receber comportamento SPA legado.

Agora, use href nos itens e navigation-mode="event" no br-breadcrumb quando a SPA for controlar a navegação.

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

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

home-url continua existindo para o destino do botão Home. Em navigation-mode="event", o Home também emite brNavigate antes de navegar.

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)

Na 1.x, o breadcrumb recebia uma lista de objetos pela propriedade links. Na 2.x, a lista passou a ser chamada de crumbs, e cada item também pode ser composto com br-breadcrumb-item.

Propriedades

API 1.x	API 2.x	Ação na migração
—	homeHref	Use para definir o destino do item inicial.
—	navigationMode	Configure a integração com a navegação da aplicação.
label	aria-label	Substitua o rótulo visual pelo nome acessível, quando necessário.
links	crumbs	Renomeie a propriedade e revise o formato dos itens.

Composição e eventos

O item inicial e os demais níveis podem ser escritos explicitamente com br-breadcrumb-item. Para interceptar a navegação, use o evento brNavigate.

Exemplo

1.x:

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

2.x:

<br-breadcrumb :crumbs="crumbs" home-href="/" aria-label="Navegação estrutural"></br-breadcrumb>