Breadcrumb communicates where the operator sits inside a hierarchy and offers shortcuts to ancestor levels. It answers "what space am I in?" without duplicating the full primary navigation. The mental model is "a shallow, stable trail that reflects real information architecture"—not a breadcrumb of filters, not a breadcrumb of tabs, not a breadcrumb of query params. Use it when the IA is 3–5 levels deep and the operator commonly arrives at a screen from multiple paths.
- The operator arrives at a screen from multiple paths (supervisor settings, analytics, QA) and needs a consistent agency → area → page mental model.
- The hierarchy is three to five levels deep and maps to real routes the operator can navigate up through.
- You need a compact alternative to repeating the full sidebar context above dense content (tables, forms, review panes).
- The app is effectively flat with one level of navigation. A single
PageHeader title suffices.
- The "trail" would mirror filters, tabs, or query params. Those are ephemeral state, not IA—use page-header metadata or chips.
- The same path is already shown in a sticky bar and the page header. Pick one location.
- The sidebar already shows the full tree and every page is one click from root. Breadcrumbs add little.
Breadcrumb wraps a BreadcrumbList of BreadcrumbItems separated by BreadcrumbSeparator. Intermediate items render as BreadcrumbLinks; the current page is a non-interactive BreadcrumbPage. Use BreadcrumbEllipsis when middle segments collapse; the collapsed segments remain reachable through an accessible disclosure.
- Short, scannable segment labels; prefer the same vocabulary as the sidebar and route titles so breadcrumbs and navigation read as one system.
- Reflect real hierarchy (agency → product area → screen), not transient UI state.
- Localize labels with
formatMessage when they aren't derived from slugs.
- Avoid duplicating the current page title in the last crumb if it matches the
PageHeader title—unless the trail is long enough that the duplication aids orientation.
- Current page. Non-interactive; styled as plain text so operators don't expect a navigation action on it.
- Ancestors. Real links that support middle-click, Cmd/Ctrl-click, and browser-back conventions.
- Unsaved work. Breadcrumb navigation should respect the same "unsaved changes" guards the rest of the product uses; don't silently discard edits on click.
- Ellipsis. The collapsed menu exposes every hidden segment and stays keyboard operable.
Do
- Keep trails shallow—three to five segments is typical. Deeper IAs often belong in the sidebar or a hub page.
- Ensure the first segment or ellipsis menu exposes the parent destination for touch and keyboard users.
- Match segment labels to the vocabulary used in the sidebar, breadcrumbs, and page titles.
Don't
- Encode filters, search queries, or tab selection in breadcrumbs. Use pills or page-subtitle patterns instead.
- Treat the breadcrumb as the only place that states critical context (e.g., read-only mode)—pair with a badge or a callout.
- Use breadcrumbs as a history trail. Browser history handles that; breadcrumbs show structure.
The component exposes a navigation landmark with a product-language accessible name. Ellipsis controls expose hidden segments in an accessible menu. See Accessibility for the full contract.
- Page header for titles, counts, and actions that sit alongside breadcrumbs.
- Crud page for list/detail shells that often host breadcrumbs.
- Tabs and Tab nav when in-module navigation should not be encoded in breadcrumbs.
