Skip to content
Nexus Application Design nadesign

Breadcrumb

<Breadcrumb> is a horizontal hierarchy: each segment is a link except the last (the current page). Use on detail pages where the parent context is non-trivial.

import from "@na/ui/components/breadcrumb" ▶ Open in Storybook packages/ui/src/components/breadcrumb.tsx

When to use

  • Detail pages two or more levels below a list (Agents > Marketing Bot > Activity).
  • Wizards or multi-step flows where the user benefits from seeing the path.

Don’t use Breadcrumb for: top-level pages (no breadcrumb needed for /agents), one-level deep pages (the page title is enough), or as primary navigation (that’s the sidebar).

Basic

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/agents">Agents</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/agents/marketing">Marketing Bot</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Activity</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

With ellipsis

When the trail is long, collapse middle segments with <BreadcrumbEllipsis>. The ellipsis is decorative — it doesn’t expand on click in this primitive (use a DropdownMenu separately if needed).

<BreadcrumbItem>
  <BreadcrumbEllipsis />
</BreadcrumbItem>

Anatomy

Breadcrumb (a <nav>) → BreadcrumbList (<ol>) → BreadcrumbItem (<li>) → BreadcrumbLink or BreadcrumbPage (the current page) + BreadcrumbSeparator between items.

Design guidelines

✓ Do

  • End the trail with BreadcrumbPage (no link). It signals "you are here."
  • Use breadcrumbs for spatial context, not navigation primary. Breadcrumbs reflect; sidebars navigate.
  • Keep segment labels short — first noun + key qualifier. "Marketing Bot" not "Marketing Bot v3 (Production)".

✗ Don't

  • Add the current page as a link. Last segment is BreadcrumbPage.
  • Render breadcrumbs on a top-level page. They look broken when there's only one segment.
  • Make breadcrumbs replace the page title. The title is hierarchical context, the breadcrumb is the trail.

Accessibility

  • Breadcrumb is a <nav aria-label="breadcrumb"> automatically.
  • The current page (BreadcrumbPage) sets aria-current="page".
  • Separators are decorative (role="presentation") — screen readers skip them.
  • PageHeader — Often hosts the Breadcrumb above the title.
  • DetailPageBar — Detail-page chrome that includes Breadcrumb.

▶ Open Breadcrumb stories in Storybook