React Breadcrumbs component

Preview

<Breadcrumbs>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item>Current page</Breadcrumbs.Item>
</Breadcrumbs>

Usage

Use when

Nested content more than two levels deep
Jumping back to a parent in one click
Documentation and catalogue hierarchies

Avoid when

Flat structures with no parents (use Tabs or header navigation)
Steps in an order (use Stepper)
Primary navigation (use Sidebar or Header)

Implementation notes

End on the current page: the last item, never a link
Short labels — the trail is a path, not a summary
Set maxItems to fold long paths into one menu, keeping the first item and the tail
Pass render for router links; href renders a plain link
Set label to rename the landmark (defaults to "Breadcrumb")
Crumbs truncate at 192px so one long title cannot push the rest out

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import Breadcrumbs once, then compose its parts with dot notation.

Breadcrumbs.Item

Each ancestor links; the last one is the current page.

<Breadcrumbs>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item>Current page</Breadcrumbs.Item>
</Breadcrumbs>

Examples

Collapsed

Past maxItems, the items after the first fold into one menu.

<Breadcrumbs maxItems={3}>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Section</Breadcrumbs.Item>
  <Breadcrumbs.Item>Current page</Breadcrumbs.Item>

Router Links

render makes the crumb your router's link.

<Breadcrumbs>
  <Breadcrumbs.Item render={<a href="#workspace" />}>Workspace</Breadcrumbs.Item>
  <Breadcrumbs.Item render={<a href="#repositories" />}>Repositories</Breadcrumbs.Item>
  <Breadcrumbs.Item>Overview</Breadcrumbs.Item>
</Breadcrumbs>

Custom Landmark Label

Renames the landmark screen readers announce.

<Breadcrumbs label="Documentation breadcrumbs">
  <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Components</Breadcrumbs.Item>
  <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>
</Breadcrumbs>

API reference

Component props
Prop	Type	Default	Description
`children`Required	`React.ReactNode`	Not set	Breadcrumb items (use Breadcrumbs.Item); the last one is the current page
`Item.children`Required	`React.ReactNode`	Not set	—
`Item.href`	`string \| undefined`	Not set	Where the crumb goes; it renders a link. Ignored on the last item, the current page.
`Item.onClick`	`React.MouseEventHandler<HTMLElement> \| undefined`	Not set	Called when the crumb is pressed. Without `href` or `render` the crumb is a button.
`Item.render`	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| undefined`	Not set	Renders the crumb as this element instead, such as a router link. It receives the crumb's class, label and handlers. Ignored on the last item.
`label`	`string \| undefined`	`Breadcrumb`	Names the navigation landmark
`maxItems`	`number \| undefined`	Not set	The most items to show; past it, the items after the first fold into one menu (needs at least 2)

Accessibility

Uses <nav aria-label="Breadcrumb"> for landmark navigation
The last item is marked with aria-current="page" and is not a link
Separators sit inside each item and are hidden from screen readers
The fold is a menu button named "Show collapsed breadcrumbs"; its crumbs are menu links

Standards references

TabsalternativeUse Tabs for flat, non-hierarchical navigation
SidebarcomplementaryBreadcrumbs complement sidebar navigation for deep hierarchies

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.