Skip to content

Path Controls

Breadcrumb renders a labeled trail of links that shows the user where the current page sits in the hierarchy and lets them step back up it. It is fully composable: you supply the items, the separators, and the page that is currently active. Long trails can be collapsed with an ellipsis.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: breadcrumb.tsx

import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@beacon/design-system";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Current Page</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Parts

Part	Role
`Breadcrumb`	Root `nav` landmark with `aria-label="breadcrumb"`. Accepts an optional `separator` node.
`BreadcrumbList`	The ordered list (`ol`) that holds the trail.
`BreadcrumbItem`	A single `li` wrapper around a link or the current page.
`BreadcrumbLink`	An `a` for an ancestor level. Pass `asChild` to render your own router link instead.
`BreadcrumbPage`	The current page: non-interactive, with `aria-current="page"`. Use this for the last item.
`BreadcrumbSeparator`	The divider between items. Defaults to a chevron; pass `children` to override it.
`BreadcrumbEllipsis`	A collapsed-range marker for hiding intermediate levels in a long trail.

`BreadcrumbLink` props

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Render the styling onto a child element (for example a framework `Link`) instead of an `a`.
`href`	`string`	n/a	Standard anchor target. All other native `a` attributes pass through.

When to use

Detail pages nested several levels deep (for example a notice inside a project inside a tenant).
Any view where the user benefits from seeing and clicking back up the hierarchy.
As secondary orientation alongside the primary nav, not as a replacement for it.

Do not use a breadcrumb as the main way to move between top-level areas; that belongs to the sidebar nav.