# Breadcrumb

> Show where a page sits in a hierarchy.

- Type: Component (disclosure)
- Access: Free, open source
- Page: https://ui.xzero.co.uk/components/breadcrumb
- Markdown: https://ui.xzero.co.uk/components/breadcrumb/markdown
- Registry item: https://mcp.xzero.co.uk/r/breadcrumb.json
- Source file: `registry/components/breadcrumb/breadcrumb.tsx`
- Dependencies: motion, lucide-react
- Keywords: navigation, wayfinding, react breadcrumb, breadcrumb navigation, animated breadcrumb, page path, nextjs breadcrumb, hierarchy navigation

## When to use

- Showing where a page sits in a hierarchy, such as Workspace, Settings, Billing.
- Client-side paths like a file browser, where crumbs call onClick instead of navigating.
- Paths that grow as people drill in, where new crumbs should slide in.

## When not to use

- Use tree-view when people need to browse the whole hierarchy.
- Use tabs for switching between sibling views.
- Use pagination for moving through pages of a list.

## Installation

Register both Xzero UI namespaces in your project's components.json:

```json
{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}
```

```bash
npx shadcn@4.23.0 add @xzero-ui/breadcrumb
```

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

## Usage

```tsx
import { Breadcrumb } from "@/components/xzero/breadcrumb/breadcrumb";

export function SettingsPath() {
  return (
    <Breadcrumb
      items={[
        { label: "Workspace", href: "/" },
        { label: "Settings", href: "/settings" },
        { label: "Billing" },
      ]}
    />
  );
}
```

## API reference

### Breadcrumb

A path of links where the last item is the current page. Crumbs added later slide in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ label: string; href?: string; onClick?: (event: MouseEvent<HTMLElement>) => void }[]` | – | Path from root to current page. Items with href render a plain a, or the link component set with XzeroProvider (such as next/link or a locale-aware Link); items with only onClick render buttons. |
| `ariaLabel` | `string` | `"Breadcrumb"` | Label for the nav landmark. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Moves between crumb links and buttons. |
| Enter | Follows the focused crumb. |

## Accessibility

- Renders a nav landmark with an ordered list.
- The last item is a span with aria-current="page" and is never a link.
- Chevron separators are aria-hidden.

## Motion

- Crumbs present on first render stay still; new crumbs slide in 8px from the left out of a blur while siblings shift on a smooth spring.
- Reduced motion adds and removes crumbs without movement.

## Responsive behavior

- The list wraps onto new lines on narrow screens; individual crumbs never wrap internally.
- It does not truncate or collapse long paths, so keep labels short or shorten the path on mobile yourself.

## Performance

- Crumbs use layout position animation only when the path changes; static paths do not animate.

## Notes for AI

- Use for hierarchical page location. For client-side paths such as a file browser, pass onClick without href.
- Links are plain anchors by default. For client-side navigation, wrap the app once in XzeroProvider from @/components/xzero/lib/xzero-provider with your router's Link: <XzeroProvider link={Link}>.
- Keep labels short; the component does not truncate or collapse long paths.

## Related

- [Tree view](https://ui.xzero.co.uk/components/tree-view/markdown): Navigate nested folders and structured content.
- [Pagination](https://ui.xzero.co.uk/components/pagination/markdown): Move through a long collection with clear bounds.
- [Tabs](https://ui.xzero.co.uk/components/tabs/markdown): Switch between related content in the same context.

## Also in navigation

- [Mega menu morph](https://ui.xzero.co.uk/components/mega-menu-morph/markdown): A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.
- [Table of contents progress](https://ui.xzero.co.uk/components/toc-progress/markdown): A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

## Guidance for AI tools

Breadcrumb: Show where a page sits in a hierarchy. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt