Breadcrumbs

Breadcrumbs help users understand where they are in a hierarchy and quickly return to a parent location. Each item can be a link, an action, a disabled label, or the current page. The component renders semantic navigation with an ordered list and accessible current-page state.

Basic usageCopy Anchor Link

Provide an ordered items array. Mark the current location with current: true; when no item is marked current, the last item is treated as current automatically.

const items = [
  { label: 'Workspace', href: '/workspace' },
  { label: 'Projects', href: '/workspace/projects' },
  { label: 'Website redesign', current: true },
];

<Breadcrumbs items={items} />

The current item is rendered as a non-link with aria-current="page". Parent items become links using their href values.

Home, icons, and separatorsCopy Anchor Link

Set showHome to prepend a home link. Use homeIcon, item icon, or a custom separator to match the navigation language of the product:

<Breadcrumbs
  showHome
  separator="/"
  items={[
    { label: 'Documentation', href: '/docs' },
    { label: 'Components', href: '/docs/components' },
    { label: 'Breadcrumbs', current: true },
  ]}
/>

separator accepts any ReactNode, including an icon or a short text character. homeIcon replaces the default home icon.

Long pathsCopy Anchor Link

Use maxItems to collapse the middle of a long path. The first and last items remain visible and the middle is replaced with an accessible button. Selecting it expands the full path:

<Breadcrumbs items={items} maxItems={4} expandLabel="Show complete path" />

Paths with two or fewer items are never collapsed. The component keeps the full list available to keyboard and assistive-technology users after expansion.

Sizes and visual variantsCopy Anchor Link

size supports xs (extra small), sm (small), and default. The default size uses a 14px font. variant="muted" reduces emphasis on the current item, while variant="pill" gives each item a filled control surface:

<Breadcrumbs size="default" items={items} />
<Breadcrumbs size="sm" variant="muted" items={items} />
<Breadcrumbs size="xs" items={items} />

Hover effectsCopy Anchor Link

Breadcrumb links use a filled background on hover by default. The effects are independent parameters, so a consumer can keep the background, replace it with an underline, or add button-like movement:

<Breadcrumbs items={items} hoverBackground />
<Breadcrumbs items={items} hoverBackground={false} hoverUnderline />
<Breadcrumbs items={items} hoverBackground={false} hoverLift />

• hoverBackground shows the filled background on hover and defaults to true.
• hoverUnderline underlines the item on hover and defaults to false.
• hoverLift moves the item up slightly on hover and returns it on press, matching the button interaction, and defaults to false.

The effects can be combined. They apply to clickable breadcrumb links and the expandable ellipsis control.

Actions and custom renderingCopy Anchor Link

Use an item's onClick or the shared onItemClick callback when a breadcrumb needs application behavior instead of ordinary navigation. Call event.preventDefault() in the callback when preventing the browser navigation is necessary.

<Breadcrumbs
  items={items}
  onItemClick={(item, index, event) => {
    analytics.track('breadcrumb_click', { index, label: item.label });
    event.preventDefault();
  }}
/>

renderItem replaces the default item rendering and receives the item, its original index, and whether it is current. Use it for badges, custom links, router integrations, or special visual states. The separator is still rendered by Breadcrumbs.

Current labels and disabled itemsCopy Anchor Link

currentLabel replaces the label of the last item without changing the source array. This is useful when the current title is loaded asynchronously. Set disabled on an item when it should remain visible but cannot be activated.

<Breadcrumbs
  currentLabel="Loading document…"
  items={[
    { label: 'Documents', href: '/documents' },
    { label: 'Quarterly report', current: true },
  ]}
/>

AccessibilityCopy Anchor Link

The component renders a nav landmark with an ordered list. Supply a more specific aria-label when a page has multiple navigation landmarks. The current item uses aria-current="page", separators are hidden from assistive technology, and links and expansion controls have visible focus styles.

API ReferenceCopy Anchor Link

BreadcrumbItemCopy Anchor Link

Theme tokensCopy Anchor Link

Breadcrumbs uses shared tokens for typography, surfaces, borders, focus, and icons. Component-only layout rules are kept in Breadcrumbs.css.