Breadcrumbs

v1.0.0 | View in Storybook Breadcrumbs are location-based, not path-based. Location-based breadcrumbs illustrate the site’s hierarchy and show the user where they are within that hierarchy. They do NOT show the path the user took to get to their current page view.

​

When to use

• When a user’s location in the app requires mutliple levels and would benefit from a clear orientation and hierarchical understanding of the app’s structure.
• When users need to quickly navigate to a parent page.

​

When to use something else

• Implementing a navigational flow for your product: Breadcrumbs should not be used as the primary source of navigation across pages.
• The page structure is flat: When users need to swap between different content or views at the same level, consider a Menu, Tabs, or Segmented control.

​

Dos and don’ts

• Don’t make the current (active) breadcrumb item navigable.
• Don’t pair with a back button. Research shows users are familiar with using a browser back button.
• Don’t wrap page names onto a second line. Truncate instead and reveal the entire name with a Tooltip.
• Don’t use multiple breadcrumbs per page.

​

Behavior

• All links within a Breadcrumb should be navigable, except the current page, and should link to their respective pages on click or with keyboard navigation (Tab / Shift+Tab and Enter).
• The separators between page links are not interactive.
• The current breadcrumb page may optionally have a dropdown menu to house additional file management actions such as renaming, duplicating or deleting the file. Review Topbar guidelines for recommended menu structure.
• When space becomes limited, use an overflow menu to truncate the Breadcrumbs. Ensure the following logic is implemented:
  1. The first and last two page links should be shown, but the remaining breadcrumbs links in between are condensed into an overflow menu.
  2. If needed, all links, including the first, can collapse into an overflow menu. However, the active (current) page name should always be visible.

​

Often used with

Tooltip on truncated crumb labels; Menu for ”…” overflow of middle segments.

​

Accessibility

• Semantic structure: Wrap components in <nav aria-label="Breadcrumb"> containing an ordered list (<ol>).
• Active state: Set aria-current="page" on the last breadcrumb item representing the current location.
• Separators: Hide visual separator icons (slashes, chevrons) from screen reader tree flows using aria-hidden="true".

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Current page linked

Use Breadcrumbs with the current page linked when the active item should remain navigable—for example, when it opens a menu with page-level actions like rename or duplicate.

​

With ellipsis dropdown

Use an ellipsis dropdown in Breadcrumbs when the path is too long to display inline; middle segments collapse into a menu while keeping the first and last items visible.

​

With badge

Add a Badge to a Breadcrumb item when the current page or parent has a status worth highlighting—for example, draft, archived, or shared.

​

Static ellipsis

Use a static ellipsis in Breadcrumbs to indicate truncated middle segments when those segments are not navigable or do not need a dropdown menu.

​

With page actions

Attach page actions to the current Breadcrumb item when file or resource management actions—such as rename, duplicate, or delete—belong at the hierarchy level of the active page.

​

Short

Use a short Breadcrumb trail when the hierarchy has only two or three levels and full path context is still clear without overflow handling.

​

Long path

Use Breadcrumbs with a long path to show deep hierarchy; apply overflow rules so users can navigate to parent levels without losing their current location.

​

Custom separator

Use a custom separator in Breadcrumbs only when product branding requires it; default separators are preferred for consistency across the application.

​

With icon

Add an icon to a Breadcrumb segment when the resource type should be visually distinguished—for example, a folder, file, or project icon beside the label.

​

Constrained container

Test Breadcrumbs in a constrained container to ensure truncation, ellipsis, and overflow menus behave correctly when horizontal space is limited.

​

Long item names

Truncate long Breadcrumb item names and reveal the full label in a Tooltip on hover or focus so paths remain scannable without breaking layout.

​

Many items

Use overflow handling when Breadcrumbs contain many items; show the first segment, an ellipsis menu for middle items, and the last two segments including the current page.

​

Single item

A single-item Breadcrumb shows only the current page when there is no parent hierarchy to display, or when the user lands at a top-level destination.

​

Empty

Handle an empty Breadcrumb state when hierarchy data is not yet loaded or unavailable; avoid rendering a broken or misleading path.

​

Small container many long items

Combine a small container with many long Breadcrumb items to validate that aggressive truncation and overflow still preserve navigation to key parent levels.