## Import
```jsx
import { Breadcrumbs } from "@cfa/react-core";
```
## Live Editor
```jsx
Page 1
Page 2
Page 3
```
## 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`.
#### Render function (recommended)
Pass `items` with a render function. React Aria handles collection wiring, including keys.
```jsx
function Example() {
const breadcrumbItems = [
{ id: 1, label: "Home", href: "/" },
{ id: 2, label: "Products", href: "/products" },
{ id: 3, label: "Sauces", href: "/products/sauces" },
];
return (
{(item) => (
{item.label}
)}
);
}
```
#### Array map
You can also render items with `.map()`, but you must add a `key` to each `Breadcrumbs.Item`.
```jsx
function Example() {
const breadcrumbItems = [
{ id: 1, label: "Home", href: "/" },
{ id: 2, label: "Products", href: "/products" },
{ id: 3, label: "Sauces", href: "/products/sauces" },
];
return (
{breadcrumbItems.map((item) => (
{item.label}
))}
);
}
```
#### Custom navigation
Use `onAction` on `Breadcrumbs.Root` instead of `href` when navigation is handled programmatically. The handler receives the pressed item's `id`.
```jsx
function Example() {
const breadcrumbItems = [
{ id: 1, label: "Home", href: "/" },
{ id: 2, label: "Products", href: "/products" },
{ id: 3, label: "Sauces", href: "/products/sauces" },
];
const navigate = (id) => {
const item = breadcrumbItems.find((entry) => entry.id === id);
console.log(item?.href);
};
return (
{(item) => (
{item.label}
)}
);
}
```
### Disabled link
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`.
```jsx
Page 1
Page 2
Page 3
```
### Current page
Omit `href` on the final `Breadcrumbs.Link` to render the current page as non-interactive text with `aria-current="page"`.
```jsx
Home
Products
Sauces
```
## Props
### Breadcrumbs.Root
| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| children | `((item: T) => ReactNode) \ | ReactNode` | - | The contents of the collection. |
| className | `string` | `'react-aria-Breadcrumbs'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| dependencies | `readonly any[]` | - | Values that should invalidate the item cache when using dynamic collections. |
| dir | `string` | - | - |
| hidden | `boolean` | - | - |
| id | `string` | - | The element's unique identifier. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Global\_attributes/id). |
| inert | `boolean` | - | - |
| items | `Iterable` | - | Item objects in the collection. |
| lang | `string` | - | - |
| onAction | `((key: Key) => void)` | - | Handler that is called when a breadcrumb is clicked. |
| onAnimationEnd | `AnimationEventHandler` | - | - |
| onAnimationEndCapture | `AnimationEventHandler` | - | - |
| onAnimationIteration | `AnimationEventHandler` | - | - |
| onAnimationIterationCapture | `AnimationEventHandler` | - | - |
| onAnimationStart | `AnimationEventHandler` | - | - |
| onAnimationStartCapture | `AnimationEventHandler` | - | - |
| onAuxClick | `MouseEventHandler` | - | - |
| onAuxClickCapture | `MouseEventHandler` | - | - |
| onClick | `MouseEventHandler` | - | - |
| onClickCapture | `MouseEventHandler` | - | - |
| onContextMenu | `MouseEventHandler` | - | - |
| onContextMenuCapture | `MouseEventHandler` | - | - |
| onDoubleClick | `MouseEventHandler` | - | - |
| onDoubleClickCapture | `MouseEventHandler` | - | - |
| onGotPointerCapture | `PointerEventHandler` | - | - |
| onGotPointerCaptureCapture | `PointerEventHandler` | - | - |
| onLostPointerCapture | `PointerEventHandler` | - | - |
| onLostPointerCaptureCapture | `PointerEventHandler` | - | - |
| onMouseDown | `MouseEventHandler` | - | - |
| onMouseDownCapture | `MouseEventHandler` | - | - |
| onMouseEnter | `MouseEventHandler` | - | - |
| onMouseLeave | `MouseEventHandler` | - | - |
| onMouseMove | `MouseEventHandler` | - | - |
| onMouseMoveCapture | `MouseEventHandler` | - | - |
| onMouseOut | `MouseEventHandler` | - | - |
| onMouseOutCapture | `MouseEventHandler` | - | - |
| onMouseOver | `MouseEventHandler` | - | - |
| onMouseOverCapture | `MouseEventHandler` | - | - |
| onMouseUp | `MouseEventHandler` | - | - |
| onMouseUpCapture | `MouseEventHandler` | - | - |
| onPointerCancel | `PointerEventHandler` | - | - |
| onPointerCancelCapture | `PointerEventHandler` | - | - |
| onPointerDown | `PointerEventHandler` | - | - |
| onPointerDownCapture | `PointerEventHandler` | - | - |
| onPointerEnter | `PointerEventHandler` | - | - |
| onPointerLeave | `PointerEventHandler` | - | - |
| onPointerMove | `PointerEventHandler` | - | - |
| onPointerMoveCapture | `PointerEventHandler` | - | - |
| onPointerOut | `PointerEventHandler` | - | - |
| onPointerOutCapture | `PointerEventHandler` | - | - |
| onPointerOver | `PointerEventHandler` | - | - |
| onPointerOverCapture | `PointerEventHandler` | - | - |
| onPointerUp | `PointerEventHandler` | - | - |
| onPointerUpCapture | `PointerEventHandler` | - | - |
| onScroll | `UIEventHandler` | - | - |
| onScrollCapture | `UIEventHandler` | - | - |
| onTouchCancel | `TouchEventHandler` | - | - |
| onTouchCancelCapture | `TouchEventHandler` | - | - |
| onTouchEnd | `TouchEventHandler` | - | - |
| onTouchEndCapture | `TouchEventHandler` | - | - |
| onTouchMove | `TouchEventHandler` | - | - |
| onTouchMoveCapture | `TouchEventHandler` | - | - |
| onTouchStart | `TouchEventHandler` | - | - |
| onTouchStartCapture | `TouchEventHandler` | - | - |
| onTransitionCancel | `TransitionEventHandler` | - | - |
| onTransitionCancelCapture | `TransitionEventHandler` | - | - |
| onTransitionEnd | `TransitionEventHandler` | - | - |
| onTransitionEndCapture | `TransitionEventHandler` | - | - |
| onTransitionRun | `TransitionEventHandler` | - | - |
| onTransitionRunCapture | `TransitionEventHandler` | - | - |
| onTransitionStart | `TransitionEventHandler` | - | - |
| onTransitionStartCapture | `TransitionEventHandler` | - | - |
| onWheel | `WheelEventHandler` | - | - |
| onWheelCapture | `WheelEventHandler` | - | - |
| render | `DOMRenderFunction<"ol", undefined>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.
Requirements:
- You must render the expected element type (e.g. if \`\