Breadcrumb

Installation

The components are exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build a breadcrumb:

Breadcrumb
└── BreadcrumbList
    ├── BreadcrumbItem
    │   ├── BreadcrumbLink
    │   └── BreadcrumbSeparator (optional)
    ├── BreadcrumbItem
    │   └── BreadcrumbEllipsis (optional)
    └── BreadcrumbItem
        └── BreadcrumbPage

BreadcrumbEllipsis is optional inside an item when collapsing middle segments—usually wrapped by a menu trigger. Separators are decorative (aria-hidden). The last segment should be a BreadcrumbPage (or a link if every segment must be actionable). This set follows the WAI-ARIA breadcrumb pattern.

Usage

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@by/experience-system';

Breadcrumb and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Current</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Examples

Overview

A standard trail with links and a BreadcrumbPage for the current location.

Custom separator

Pass children to BreadcrumbSeparator to replace the default chevron.

With ellipsis

Collapse middle segments behind BreadcrumbEllipsis and a DropdownMenu trigger.

API Reference

Subsection titles name the exports from @by/experience-system. These are semantic HTML wrappers (not Radix primitives).

Root nav. Defaults aria-label to breadcrumb.

Prop	Type	Default
`aria-label`	`string`	`breadcrumb`

Data attribute	Values
`data-slot`	`breadcrumb`

Also accepts standard nav attributes.

BreadcrumbList

Ordered list container.

Data attribute	Values
`data-slot`	`breadcrumb-list`

Also accepts standard ol attributes.

BreadcrumbItem

List item wrapper for each segment.

Data attribute	Values
`data-slot`	`breadcrumb-item`

Also accepts standard li attributes.

BreadcrumbLink

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`data-slot`	`breadcrumb-link`

Also accepts standard a attributes when asChild is false. With asChild, props merge onto the child element (for example Link from your router).

BreadcrumbPage

Non-interactive current page segment.

Data attribute	Values
`data-slot`	`breadcrumb-page`

Renders with role="link", aria-disabled="true", and aria-current="page". Also accepts standard span attributes.

BreadcrumbSeparator

Prop	Type	Default
`children`	`React.ReactNode`	chevron icon

Data attribute	Values
`data-slot`	`breadcrumb-separator`

Decorative: role="presentation" and aria-hidden. Also accepts standard span attributes.

BreadcrumbEllipsis

Data attribute	Values
`data-slot`	`breadcrumb-ellipsis`

Includes visually hidden “More” text. Also accepts standard span attributes.

Accessibility

Use a nav landmark with a clear label (default aria-label="breadcrumb"). Mark the current page with BreadcrumbPage so aria-current="page" is exposed. Keep separators decorative. When collapsing segments, provide a focusable control that reveals the hidden trail (for example a menu), not BreadcrumbEllipsis alone. See the WAI-ARIA breadcrumb pattern.

Keyboard interactions

Key	Description
`Tab`	Moves focus through links and interactive controls (for example the ellipsis trigger).
`Enter` / `Space`	Activates focused links or the ellipsis trigger when implemented as a button.

Source in the repo: packages/experience-system/src/components/Breadcrumb/Breadcrumb.tsx. Agent-oriented contracts: packages/experience-system/src/components/Breadcrumb/Breadcrumb.instructions.md.

Breadcrumb

On this page