Breadcrumb

v1.0.10

Ready for Production

Catalyst Breadcrumb is a fully accessible, compound navigation component built on semantic HTML with built-in design tokens and focus styles — so you get a production-ready breadcrumb trail with correct ARIA semantics and zero configuration.

Installation

npm install @pmi/catalyst-breadcrumb

import {
  BreadcrumbRoot,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbPage,
  BreadcrumbEllipsis,
} from '@pmi/catalyst-breadcrumb';

Common Patterns

With Dropdown Menu

Use BreadcrumbEllipsis with a dropdown menu to show collapsed breadcrumb items.

API Reference

Breadcrumb is a compound component. Each subcomponent maps to a semantic HTML element and forwards its ref.

BreadcrumbRoot

The outermost wrapper. Renders a <nav> element with aria-label="Breadcrumb".

Accepts all standard HTML nav attributes and forwards ref to the underlying HTMLElement.

BreadcrumbList

Renders an <ol> element that lays out breadcrumb items in a horizontal, wrapping row.

Accepts all standard HTML ol attributes and forwards ref to the underlying HTMLOListElement.

BreadcrumbItem

Renders an <li> element that wraps a single breadcrumb entry.

Accepts all standard HTML li attributes and forwards ref to the underlying HTMLLIElement.

BreadcrumbLink

Renders an <a> element (or a custom element via asChild) for navigable breadcrumb steps.

Accepts all standard HTML anchor attributes and forwards ref to the underlying HTMLAnchorElement.

BreadcrumbPage

Renders a <span> for the current page in the trail. Automatically sets aria-current="page", role="link", and tabIndex={0} so the current item is focusable and screen readers can identify it as a link-like element marking the active page.

Accepts all standard HTML span attributes and forwards ref to the underlying HTMLSpanElement.

BreadcrumbSeparator

Renders a presentational <li> with role="presentation" and aria-hidden="true". Place any icon or character as a child.

Accepts all standard HTML li attributes and forwards ref to the underlying HTMLSpanElement (inner wrapper).

BreadcrumbEllipsis

Renders a <span> with role="presentation" and aria-label="More" for collapsed items. Typically used as the trigger for a dropdown.

Accepts all standard HTML span attributes and forwards ref to the underlying HTMLSpanElement.

Accessibility

Keyboard Interactions

Breadcrumb relies entirely on standard browser keyboard behavior. BreadcrumbLink uses a native <a> element — reachable via Tab and activatable via Enter. BreadcrumbPage renders with role="link" and tabIndex={0}, so it is reachable via Tab and focusable by screen readers to announce the current page, but it carries no onClick or onKeyDown activation handler — pressing Enter or Space has no effect.

ARIA

Catalyst adds the following ARIA semantics automatically — you do not need to set these manually:

• BreadcrumbRoot renders <nav aria-label="Breadcrumb"> — announces the landmark to screen readers as a breadcrumb navigation region.
• BreadcrumbPage marks the current item with aria-current="page" and role="link" — tells screen readers which entry is the active page and presents it as a link-like landmark; tabIndex={0} keeps it reachable via keyboard.
• BreadcrumbSeparator renders role="presentation" and aria-hidden="true" — hides decorative separators from the accessibility tree.
• BreadcrumbEllipsis renders role="presentation" and aria-label="More" — provides a readable label for the collapsed items indicator.

What you are responsible for:

• Provide meaningful link text in BreadcrumbLink — avoid generic labels like "click here".
• When using BreadcrumbEllipsis with a dropdown, ensure the dropdown trigger has a visible focus style and an accessible label (the aria-label="More" on BreadcrumbEllipsis covers this by default).
• If you replace the separator icon, keep it visually distinct but ensure it stays hidden from screen readers (aria-hidden is applied by BreadcrumbSeparator automatically).

Choosing the Right Component

Use Breadcrumb when you need to show a user's location within a multi-level hierarchy and let them navigate back up. Reach for a different primitive when:

Related

• Dropdown Menu
• Link
• Navigation Menu
• Stepper