Skip to content
CFA Design System

Breadcrumbs

ReactProps
Github icon-storybook-square Storybook Markdown Copy for LLM

Breadcrumbs display a hierarchy of links to the current page or resource in an application.

Import

import { Breadcrumbs } from "@cfa/react-core";

Live Editor

Guidelines

When to use

  • Breadcrumbs is for showing where people are in a hierarchical site and linking to ancestor pages, especially when they arrive through search, a deep link, or a shared URL.

Do

  • Use Breadcrumbs when the site has at least three levels and primary navigation alone does not make the hierarchy obvious.
  • Start with Home as an icon or text link. End with the current page as plain text, not a link.
  • Separate items with a chevron (›). Use a forward slash (/) only for a lighter, path-like look.
  • Show at most four ancestor links plus the current page. The component does not truncate or overflow.
  • Use Breadcrumbs with primary navigation, such as SideNavigation or Tabs.

Avoid

  • Making Breadcrumbs the only way to navigate.
  • Using Breadcrumbs on a flat or shallow site, the homepage, or a page with no ancestors.
  • Using Breadcrumbs in a linear flow such as checkout or a wizard. Use Stepper.
  • Using Breadcrumbs when SideNavigation already makes the hierarchy obvious. Breadcrumbs may be redundant there.
  • Building a path that needs more than four ancestors. Flatten the hierarchy or use SideNavigation.

Composition

Breadcrumbs is built from three parts:

  • Breadcrumbs.Root — the navigation landmark and list container
  • Breadcrumbs.Item — one segment in the trail
  • Breadcrumbs.Link — the interactive link, or plain text for the current page

Examples

Dynamic items

Use the items prop when breadcrumb data comes from an array or API. Each item should include an id.

Pass items with a render function. React Aria handles collection wiring, including keys.

Array map

You can also render items with .map(), but you must add a key to each Breadcrumbs.Item.

Custom navigation

Use onAction on Breadcrumbs.Root instead of href when navigation is handled programmatically. The handler receives the pressed item’s id.

Use isDisabled on Breadcrumbs.Link to prevent navigation for a non-current ancestor. This is uncommon; most trails disable only the current page or omit its href.

Current page

Omit href on the final Breadcrumbs.Link to render the current page as non-interactive text with aria-current="page".