# Breadcrumbs

Shows where the current page sits in the site hierarchy.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Breadcrumbs.tsx)

## Overview

A trail of links from the current page back to its ancestors.

## Examples

### Basic

```tsx
import { Breadcrumbs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Breadcrumbs>
      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
      <Breadcrumbs.Item href="#">Payments</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Invoices</Breadcrumbs.Item>
    </Breadcrumbs>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Breadcrumbs/Basic.tsx)

### Separator

Set `separator` to any node to place between items. It defaults to a right chevron.

```tsx
import { Breadcrumbs } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Breadcrumbs separator="/">
      <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
      <Breadcrumbs.Item current>Guides</Breadcrumbs.Item>
    </Breadcrumbs>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Breadcrumbs/Separator.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Breadcrumbs } from '@tempoxyz/ds'

<Breadcrumbs>
  <Breadcrumbs.Item />
</Breadcrumbs>
```

## Guidelines

### When to Use

* Mark pages three or more levels deep, such as a webhook endpoint inside a project in Tempo Console.
* Mark detail pages that people reach from a list and return to often, such as one API key under Checkout › API keys.

### When Not to Use

* Use [SidebarMenu](/docs/components/sidebar-menu) to move between top-level sections.
* Use [Stepper](/docs/components/stepper) to show progress through a flow, such as Send payment.
* Use [Tabs](/docs/components/tabs) to switch between views of the same page.
* Use `Button.Link` from [Button](/docs/components/button) with `variant="tertiary"` for a single Back link in a two-level product.

### Reserve Breadcrumbs for Deep Hierarchies

Add a trail only at three or more levels deep. On shallower pages, a trail repeats the sidebar and the page title.

**Do:** Show a trail on a page nested under a project and a section.

```tsx
/**
 * Do example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
 * Show a trail on a page nested under a project and a section.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>Production</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Add a trail to a top-level page, where it repeats the sidebar.

```tsx
/**
 * Don't example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
 * Don't add a trail to a top-level page, where it repeats the sidebar.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Activity</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>Activity</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

### Reflect the Hierarchy, Not History

Build the trail from the product's structure. A transaction page shows the same trail from Activity, a search result, or a shared link. The browser's Back button covers history.

**Do:** Show the pages that contain the current page.

```tsx
/**
 * Do example for "Reflect the Hierarchy, Not History" on the Breadcrumbs page.
 * Show the pages that contain the current page.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">Activity</Breadcrumbs.Item>
        <Breadcrumbs.Item current>0x8f3a…c21d</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>0x8f3a…c21d</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** List the pages someone visited on the way.

```tsx
/**
 * Don't example for "Reflect the Hierarchy, Not History" on the Breadcrumbs page.
 * Don't list the pages someone visited on the way.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Search</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">Wallets</Breadcrumbs.Item>
        <Breadcrumbs.Item current>0x8f3a…c21d</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>0x8f3a…c21d</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

### Place the Trail Above the Title

Put breadcrumbs at the start of the content column, in the same position on every page.

**Do:** Place the trail directly above the page title.

```tsx
/**
 * Do example for "Reserve Breadcrumbs for Deep Hierarchies" on the Breadcrumbs page.
 * Show a trail on a page nested under a project and a section.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>Production</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Place the trail below the title.

```tsx
/**
 * Don't example for "Place the Trail Above the Title" on the Breadcrumbs page.
 * Don't place the trail below the title.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <span {...styles.title()}>Production</span>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">API keys</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Production</Breadcrumbs.Item>
      </Breadcrumbs>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

### Keep the Default Separator

The default right chevron reads as one step down the hierarchy. Set `separator` only if the product already uses another convention, such as `/` for documentation paths, and use one separator across the product.

**Do:** Keep the default chevron.

```tsx
/** Do example for "Keep the Default Separator" on the Breadcrumbs page: keep the default chevron. @module */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs>
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Deliveries</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>Deliveries</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

**Don't:** Swap in another separator, such as an arrow, without a product convention.

```tsx
/**
 * Don't example for "Keep the Default Separator" on the Breadcrumbs page.
 * Don't swap in another separator, such as an arrow, without a product convention.
 * @module
 */
import { Breadcrumbs, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.page()}>
      <Breadcrumbs separator="→">
        <Breadcrumbs.Item href="#">Checkout</Breadcrumbs.Item>
        <Breadcrumbs.Item href="#">Webhooks</Breadcrumbs.Item>
        <Breadcrumbs.Item current>Deliveries</Breadcrumbs.Item>
      </Breadcrumbs>
      <span {...styles.title()}>Deliveries</span>
    </div>
  )
}

namespace styles {
  export const page = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const title = style({ color: 'content.primary', typography: 'heading.h2' })
}
```

## Content

* **Labels:** Use each page's title, such as API keys.
* **Addresses and hashes:** Shorten to the first and last characters, such as 0x71C7…976F. Show the full value on the page.
* **Length:** The list wraps instead of truncating, so keep labels short.

## Accessibility

Renders a navigation landmark with an ordered list of links, following the [WAI-ARIA breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).

### Semantics

* **Root (nav):** A navigation landmark named "Breadcrumb".
* **List (ol):** Screen readers announce the number of levels.
* **Breadcrumbs.Item (li):** Wraps a link. The current item is plain text marked as the current page.
* **Separators (aria-hidden):** Hidden. Screen readers announce only the pages.

### Keyboard

* **Move Between Links (Tab):** Moves focus to each link in order, skipping the current item.
* **Follow a Link (Enter):** Follows the focused link.

### Your Responsibilities

* **Mark the Current Page (current):** Set it on the last item. It is announced as the current page and takes no focus.
* **Keep the Landmark Distinct (SC 2.4.1):** Keep the "Breadcrumb" name, or pass a distinct `aria-label`.
* **Use Real Links (render):** Pass your router's link so each item stays a real link with the same styles.
* **Keep the Default Gaps (20px):** Links are under the 24px minimum, which WCAG 2.2 accepts if targets are spaced apart.

## Related

[SidebarMenu](/docs/components/sidebar-menu)

Use for top-level navigation.

[AppShell](/docs/components/app-shell)

Use for the page frame that holds the trail.

[Tabs](/docs/components/tabs)

Use for switching views within a page.

[Navigation](/docs/patterns/navigation)

Covers choosing between navigation components.
