# Breadcrumbs

> Shows where the current page sits in a hierarchy and links back up it.

Category: Navigation · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/breadcrumbs

Use Breadcrumbs on pages that are two or more levels deep, such as a template inside a team inside an organisation. They complement, not replace, primary navigation. Long trails collapse their middle items behind an expandable ellipsis, and on screens narrower than 640px they collapse to the first and last items.

## Import

```tsx
import { Breadcrumbs, BreadcrumbItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { BreadcrumbItem, Breadcrumbs } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Breadcrumbs>
      <BreadcrumbItem href="#dashboard">Dashboard</BreadcrumbItem>
      <BreadcrumbItem href="#templates">Templates</BreadcrumbItem>
      <BreadcrumbItem current>Sales signature</BreadcrumbItem>
    </Breadcrumbs>
  );
}
```

### Collapsed trail

More items than maxItems collapse behind an ellipsis button that reveals them and moves focus to the first revealed link.

```tsx
import { BreadcrumbItem, Breadcrumbs } from '@bindshq/stance-react';

export function Collapsed() {
  return (
    <Breadcrumbs maxItems={3}>
      <BreadcrumbItem href="#org">Binds</BreadcrumbItem>
      <BreadcrumbItem href="#teams">Teams</BreadcrumbItem>
      <BreadcrumbItem href="#sales">Sales</BreadcrumbItem>
      <BreadcrumbItem href="#emea">EMEA</BreadcrumbItem>
      <BreadcrumbItem href="#templates">Templates</BreadcrumbItem>
      <BreadcrumbItem current>Q4 campaign banner</BreadcrumbItem>
    </Breadcrumbs>
  );
}
```

### Custom separator and icons

```tsx
import { BreadcrumbItem, Breadcrumbs, Icon } from '@bindshq/stance-react';

export function CustomSeparator() {
  return (
    <Breadcrumbs separator="/">
      <BreadcrumbItem href="#home" icon={<Icon name="home" size={14} />}>
        Home
      </BreadcrumbItem>
      <BreadcrumbItem href="#settings">Settings</BreadcrumbItem>
      <BreadcrumbItem current>Billing</BreadcrumbItem>
    </Breadcrumbs>
  );
}
```

### With router links

Use asChild to render your framework link component, such as Next.js Link.

```tsx
import { BreadcrumbItem, Breadcrumbs } from '@bindshq/stance-react';

export function WithRouterLinks() {
  // Replace <a> with your router's Link component.
  return (
    <Breadcrumbs>
      <BreadcrumbItem asChild>
        <a href="#workspace">Workspace</a>
      </BreadcrumbItem>
      <BreadcrumbItem asChild>
        <a href="#integrations">Integrations</a>
      </BreadcrumbItem>
      <BreadcrumbItem current>Exchange relay</BreadcrumbItem>
    </Breadcrumbs>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Breadcrumbs | `label` | `string` | `'Breadcrumb'` | Accessible name of the navigation landmark. |
| Breadcrumbs | `separator` | `ReactNode` | `chevron icon` | Content between items; always hidden from assistive technology. |
| Breadcrumbs | `maxItems` | `number` | `5` | Collapse middle items when there are more items than this. |
| Breadcrumbs | `itemsBeforeCollapse` | `number` | `1` | Items kept before the ellipsis. |
| Breadcrumbs | `itemsAfterCollapse` | `number` | `2` | Items kept after the ellipsis. |
| Breadcrumbs | `collapseOnMobile` | `boolean` | `true` | Below 640px, show only the first and last items. |
| Breadcrumbs | `expandLabel` | `string` | `'Show all breadcrumbs'` | Accessible label for the ellipsis button. |
| Breadcrumbs | `size` | `'sm' \| 'md'` | `'md'` | Text size. |
| BreadcrumbItem | `href` | `string` | None | Destination. Items without href render as text. |
| BreadcrumbItem | `current` | `boolean` | `false` | Marks the current page with aria-current="page" and renders plain text. |
| BreadcrumbItem | `icon` | `ReactNode` | None | Icon before the label. |
| BreadcrumbItem | `asChild` | `boolean` | `false` | Render your own link element with breadcrumb styles. |

## Accessibility

- Renders a <nav> landmark with an accessible name and an ordered list, so screen readers announce the number of levels.
- The current page is plain text with aria-current="page"; it is not a link to itself.
- Separators are aria-hidden, so they are not read as “greater than” or similar.
- The ellipsis is a real button announcing how many items are hidden; after expanding, focus moves to the first revealed link.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves between links and the expand button. |
| `Enter` | Follows a link or expands the collapsed items. |

## Guidelines

**Do**

- Use the page title as the last item.
- Keep labels short; long labels truncate at 16rem.

**Don’t**

- Use breadcrumbs for linear flows; use Stepper.
- Show breadcrumbs on top-level pages where there is nothing above.

## Related

- https://stanceui.com/components/sidebar
- https://stanceui.com/components/tabs
- https://stanceui.com/components/link