Breadcrumb

Trilha hierárquica para hierarquias com ≥3 níveis — orientação espacial sem custo de cliques.

Overview

Breadcrumb mostra onde o usuário está dentro de uma hierarquia e oferece um caminho de volta. Reservar para sites com hierarquia real — ≥3 níveis. Em sites flat (3 páginas top-level), breadcrumb adiciona ruído sem ganho.

A última posição é a página atual e não deve ser link — <BreadcrumbPage> aplica aria-current="page" para que SRs anunciem corretamente. Em mobile com hierarquias profundas, prefira a versão colapsada com <BreadcrumbEllipsis> revelando os passos intermediários via popover.

Preview

Trilha padrão com chevron como separador.

Anatomy

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/" />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage />          ← último item, sem link
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Markup nativo: <nav> + <ol> + <li>. Sem dependências, sem JavaScript de runtime; SSR-friendly por padrão.

Subcomponents

Componente	Descrição
`Breadcrumb`	`<nav aria-label="breadcrumb">`.
`BreadcrumbList`	`<ol>` que enfileira os itens.
`BreadcrumbItem`	`<li>` para cada nível.
`BreadcrumbLink`	Link clicável; aceita `asChild` para integrar com routers.
`BreadcrumbPage`	Página atual — não navegável, com `aria-current="page"`.
`BreadcrumbSeparator`	Separador (chevron padrão; passa `children` para customizar).
`BreadcrumbEllipsis`	Indica passos colapsados, geralmente acoplado a um Popover/Dropdown.

Usage

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator
} from "@kalvner/kds/navigation/breadcrumb";

export function PageTrail() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Settings</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

Variants

Custom separator

Slash, dot, ou ícone próprio — passe via children.

Collapsed middle

Para hierarquias profundas em mobile.

Deeply nested

Quando todos os níveis são relevantes.

When to use

Sites e apps com hierarquia ≥3 níveis — admin, e-commerce, doc trees, knowledge bases.
Quando o usuário navegou via search ou link direto e não tem contexto da posição.
Em settings com múltiplas seções aninhadas.

When not to use

Sites flat (≤2 níveis): adiciona ruído sem benefício.
Em fluxos lineares (checkout, wizard) — use Stepper.
Como navegação primária — Breadcrumb é orientação, não menu.
Quando a hierarquia muda dinamicamente sem padrão estável.

Best practices

Página atual nunca é link. Use <BreadcrumbPage> no último nível; SRs anunciam como aria-current="page".
Mostre o caminho real. Se o usuário chegou em /posts/123 via search, ainda assim mostre Home > Blog > Título. A trilha é uma promessa do site, não do histórico de navegação.
Mobile colapsa. Em telas estreitas, Home > ... > Atual
- Popover. Não tente fazer scroll horizontal.
Limite até 6 níveis. Acima disso a hierarquia provavelmente está mal estruturada.
Não use ícones sozinhos. Texto sempre. Ícone como reforço, não substituição.

Accessibility

Concern	Comportamento
Roles	`<nav aria-label="breadcrumb">` envolve uma `<ol>` ordenada.
Current page	`BreadcrumbPage` aplica `role="link"` + `aria-disabled="true"` + `aria-current="page"` para SRs.
Keyboard	Tab segue a ordem do DOM; cada link é focável. Os separadores são `aria-hidden`.
Screen reader	Anunciado como "navigation, breadcrumb". Os itens são anunciados em ordem.
Custom separator	Garanta `aria-hidden="true"` no ícone (já aplicado pelo `BreadcrumbSeparator`).

Pagination — para navegar páginas de uma lista, não para hierarquia.
NavigationMenu — navegação top-level com painéis ricos.
Tabs — alternar views dentro do mesmo escopo.

Breadcrumb

On this page