Breadcrumb

O mk-breadcrumb exibe o caminho percorrido desde a raiz até a página atual em uma sequência de links separados por um divisor (/). Ele orienta o usuário em estruturas com múltiplos níveis e oferece atalhos para voltar a qualquer nível anterior sem usar o botão "voltar" do navegador. A página atual é sempre o último item da trilha e não é clicável.

Quando usar

• A interface tiver hierarquia de navegação com 2 ou mais níveis
• O usuário precisar entender sua localização dentro de uma estrutura de páginas
• A navegação de retorno para níveis superiores for frequente

• A interface for plana, sem hierarquia de páginas — o breadcrumb seria vazio de significado
• O espaço horizontal for muito limitado e o contexto de localização não for prioritário

Anatomia

O breadcrumb é uma sequência horizontal de itens alternados entre links de página e separadores.

Padrão

Passe um array de objetos { label, href } na prop items. O último item é automaticamente tratado como a página atual — omita o href nele.

import { MkBreadcrumb } from '@db1/makuco-ui-react';

<MkBreadcrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Produtos', href: '/products' },
    { label: 'Detalhes', href: '/products/123' },
    { label: 'Página atual' },
  ]}
  onMkNavigate={(e) => router.navigate(e.detail.href)}
/>

<mk-breadcrumb
  [items]="breadcrumbItems"
  (mkNavigate)="onNavigate($event)"
></mk-breadcrumb>

breadcrumbItems = [
  { label: 'Home', href: '/' },
  { label: 'Produtos', href: '/products' },
  { label: 'Detalhes', href: '/products/123' },
  { label: 'Página atual' },
];

onNavigate(event: CustomEvent<{ href: string }>) {
  this.router.navigate([event.detail.href]);
}

Caminho curto

Com apenas 2 itens — raiz e página atual.

<MkBreadcrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Página atual' },
  ]}
/>

<mk-breadcrumb [items]="[
  { label: 'Home', href: '/' },
  { label: 'Página atual' }
]"></mk-breadcrumb>

Caminho longo

Suporta até 7 níveis de profundidade.

<MkBreadcrumb
  items={[
    { label: 'Dashboard', href: '/' },
    { label: 'Configurações', href: '/settings' },
    { label: 'Conta', href: '/settings/account' },
    { label: 'Segurança', href: '/settings/account/security' },
    { label: 'Autenticação em dois fatores' },
  ]}
/>

<mk-breadcrumb [items]="deepPath"></mk-breadcrumb>

Comportamento

Os separadores (/) são inseridos automaticamente entre os itens — não é necessário adicioná-los manualmente. O último item do array é sempre tratado como a página atual: é renderizado como <span> com aria-current="page" e não dispara mkNavigate ao ser clicado.

Itens anteriores ao atual com href são links reais (<a href>). O clique simples emite mkNavigate e cancela a navegação nativa, para integração com roteadores client-side: ouça o evento e execute a navegação programática. Clique com Ctrl, Cmd, Shift ou Alt e o botão do meio seguem o comportamento nativo do link (abrir em nova aba, copiar endereço). Itens sem href são renderizados como botão.

Abaixo de 768 px, cada item ocupa uma linha: o primeiro sem recuo e os demais com recuo de var(--db1-spacing-2), com a barra antes do link. O texto do item quebra linha, inclusive palavras longas sem espaço. Com collapseOnMobile, abaixo de 768 px aparecem só o primeiro e o último item, na mesma linha e sem recuo; os intermediários saem da tela e da árvore de acessibilidade.

Composição

O mk-breadcrumb é um componente de navegação secundária. Posicione-o próximo ao topo da página, abaixo do cabeçalho global e acima do título da página atual.

Não combine mk-breadcrumb com outros indicadores de localização na mesma área — ele é o único elemento responsável por comunicar a posição hierárquica do usuário.

Props

Eventos

Acessibilidade

Landmark de navegação: o elemento <mk-breadcrumb> recebe role="navigation" e um aria-label traduzido pelo locale ("Trilha de navegação", "Ruta de navegación" ou "Breadcrumb") diretamente no host, identificando o bloco como navegação secundária para leitores de tela. Internamente, a trilha é renderizada como <ol> com itens <li> — semântica de lista ordenada, compatível com a leitura sequencial esperada por tecnologias assistivas.

Página atual: o último item recebe automaticamente aria-current="page". Sem esse atributo, usuários de leitores de tela não conseguiriam distinguir o item ativo dos links anteriores.

Separadores decorativos: os separadores (/) são marcados com aria-hidden="true" e não são lidos — eles não carregam informação semântica.

Navegação por teclado: os itens anteriores ao atual com href são links <a> e, sem href, botões (via mk-link); todos alcançáveis via Tab. O item atual é um <span> e não entra no fluxo de foco.

• 1.3.1 Informação e relações (A): trilha em lista ordenada (<ol>/<li>) dentro de um landmark de navegação.
• 4.1.2 Nome, função, valor (A): o item que leva a outra página é um link (role="link"), não um botão.
• 2.4.4 Finalidade do link (A): o texto de cada item descreve o destino.
• 2.1.1 Teclado e 2.4.7 Foco visível (A, AA): os links entram na ordem de Tab, com foco visível.
• 3.1.2 Idioma das partes (AA): o nome do landmark segue o locale.
• 1.4.10 Refluxo (AA): sem rolagem horizontal em 320 px.
• 2.4.8 Localização (AAA): a trilha é a técnica G65.

O padrão Breadcrumb do APG acrescenta aria-current="page" no item da página atual e separadores decorativos fora da leitura (aria-hidden="true").

Atualizando de versões anteriores

• O ancestral com href passa de <button> para link <a> (role="link"). Seletores de teste por role=button deixam de encontrá-lo.
• O link ativa com Enter; Espaço deixa de ativar.
• O clique simples emite mkNavigate com o mesmo { href } e cancela a navegação nativa. Clique com Ctrl, Cmd, Shift ou Alt e o botão do meio abrem o href nativo e não emitem o evento; o href deve ser a URL final que o app aceita (com base path ou hash).
• O aria-label do landmark deixa de ser "breadcrumb" e passa a seguir o locale. Seletores de teste por aria-label="breadcrumb" deixam de encontrá-lo.
• Abaixo de 768 px, cada item ocupa uma linha, com recuo nos itens após o primeiro.
• A barra passa a ser desenhada antes de cada item a partir do segundo, e a ordem do DOM muda: snapshots de HTML dos consumidores mudam. O visual no desktop é o mesmo.