# Breadcrumb

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

- **Import:** `import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis } from "@booleanpress/ui/breadcrumb"`
- **APG Breadcrumb:** <https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/>
- **Page:** <https://ui.booleanpress.com/components/breadcrumb> · @booleanpress/ui 0.1.0

## Usage

A breadcrumb is a list of links ending in the current page. Put `BreadcrumbSeparator` between items, as a sibling of the items inside `BreadcrumbList`.

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@booleanpress/ui/breadcrumb"

export function Trail() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/mailers">Mailers</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Primary mailer</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

With a router, pass its link with `asChild`: `<BreadcrumbLink asChild><Link to="/mailers">Mailers</Link></BreadcrumbLink>`. `BreadcrumbEllipsis` stands for hidden levels; make it a link or the trigger of a [dropdown menu](/components/dropdown-menu) to reveal them. `BreadcrumbSeparator` shows a chevron that points along the reading direction; pass children to use another mark.

## Examples

### Basic

Two links and the current page.

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@booleanpress/ui/breadcrumb"

export default function BreadcrumbBasic() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Mailers</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Primary mailer</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Connection</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### Collapsed levels

`BreadcrumbEllipsis` stands for levels that are left out.

```tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@booleanpress/ui/breadcrumb"

export default function BreadcrumbEllipsisExample() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Tickets</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Acme Ltd</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Refund request</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### With a menu

An item opens a dropdown menu to switch to a sibling.

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@booleanpress/ui/breadcrumb"
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@booleanpress/ui/dropdown-menu"
import { ChevronDownIcon } from "lucide-react"

export default function BreadcrumbDropdown() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">People</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger className="flex items-center gap-1 rounded-sm outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring">
              Organizations
              <ChevronDownIcon className="size-3.5" aria-hidden="true" />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuItem>Acme Ltd</DropdownMenuItem>
              <DropdownMenuItem>Northwind</DropdownMenuItem>
              <DropdownMenuItem>Globex</DropdownMenuItem>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Dana Whitfield</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

### Custom separator

Children of `BreadcrumbSeparator` replace the chevron.

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@booleanpress/ui/breadcrumb"

export default function BreadcrumbCustomSeparator() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Settings</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>/</BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Logging</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>/</BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>Retention</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

## Accessibility

**Semantics.** A `nav` landmark named from the provider's `breadcrumb` string, holding an ordered list. The current page is a `span` with `aria-current="page"`, and the separators are hidden from assistive technology.

**Labels.** The landmark's name comes from the provider's `breadcrumb` string; translate it there. The ellipsis carries a visually hidden label from the provider's `more` string.

**Focus.** Each link is in the tab order. The current page and the ellipsis are not focusable, so a collapsed level needs a link or a menu trigger around the ellipsis to be reachable.

**Known limits.**

- `BreadcrumbPage` has `role="link"` with `aria-disabled="true"`, as in shadcn/ui, so a screen reader announces a disabled link.
- `BreadcrumbEllipsis` is hidden from assistive technology (`aria-hidden`), so its visually hidden label is never read; name the control that wraps it.

### Keyboard

| Key | Behaviour |
| --- | --- |
| Tab | Moves between the links. The current page is skipped. |

## API

### Breadcrumb

Renders a `nav` and passes it every other prop.

### BreadcrumbList

Renders a `ol` and passes it every other prop.

### BreadcrumbItem

Renders a `li` and passes it every other prop.

### BreadcrumbLink

Renders a `a` and passes it every other prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Render the child element instead, such as a router link, with this part's classes merged onto it. |

### BreadcrumbPage

Renders a `span` and passes it every other prop.

### BreadcrumbSeparator

Renders a `li` and passes it every other prop.

### BreadcrumbEllipsis

Renders a `span` and passes it every other prop.

Every part takes `className`, merged with its defaults by `cn()`, and `ref`, which reaches the element it renders.

**Data attributes:** `data-slot="breadcrumb"` (Breadcrumb), `data-slot="breadcrumb-list"` (BreadcrumbList), `data-slot="breadcrumb-item"` (BreadcrumbItem), `data-slot="breadcrumb-link"` (BreadcrumbLink), `data-slot="breadcrumb-page"` (BreadcrumbPage), `data-slot="breadcrumb-separator"` (BreadcrumbSeparator), `data-slot="breadcrumb-ellipsis"` (BreadcrumbEllipsis).

**Provider strings:** `breadcrumb`, `more` (`BooleanUIProvider`'s `strings`).

## Theming

Links are `--muted-foreground` and turn `--foreground` on hover; the current page is `--foreground`.

| Token | Used for |
| --- | --- |
| `--foreground` | text |
| `--muted-foreground` | text |