# Breadcrumb

The path from the top of the app to the current page: Projects, Werewolf, Settings. Each ancestor is a link in secondary text; the current page is primary text, not a link. A caret sits between them.

## Usage

### When to use

- Show where a page sits on pages two or more levels deep, above the page title: Projects, Werewolf, Settings.
- Let users go back up to any parent page in one step.

### When not to use

- The steps of a flow, such as checkout.
- The main navigation of the app.
- Sections of one page. Use Tabs.

## Examples

### Path

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="#werewolf">Werewolf</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Settings</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### Long path

The middle steps sit in a menu behind a named trigger.

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button variant="ghost" size="sm" iconOnly aria-label="Show the full path">
            <BreadcrumbEllipsis />
          </Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent>
          <DropdownMenuItem asChild>
            <a href="#werewolf">Werewolf</a>
          </DropdownMenuItem>
          <DropdownMenuItem asChild>
            <a href="#components">Components</a>
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Button</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Do and don't

### Do

- Show it on pages two or more levels deep, above the page title.
- Name each step as its page is titled.
- Collapse the middle of a long path into a menu, and keep the first and the last two steps.

### Don't

- Don't make the current page a link.
- Don't use it for the steps of a flow; it shows where a page sits, not progress.
- Don't use it as the only navigation of the app.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` |  | `false` | Set on BreadcrumbLink. Renders the child (the app's router link) with the link's look. |

### Slots

| Name | Required | Description |
| --- | --- | --- |
| `list` | yes | BreadcrumbList with a BreadcrumbItem per step and a BreadcrumbSeparator between steps. The last item holds a BreadcrumbPage. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | Breadcrumb: a nav named Breadcrumb. |
| `list` | BreadcrumbList: the steps in a row that wraps, 13px secondary text, gap-sm. |
| `item` | BreadcrumbItem: one step. |
| `link` | BreadcrumbLink: an ancestor, a link in secondary text that turns primary and underlined on hover. asChild takes the app's own link component. |
| `current` | BreadcrumbPage: the current page in primary text, aria-current="page". |
| `separator` | BreadcrumbSeparator: a Tabler ChevronRight, 16px, secondary; pass children for another mark. |
| `ellipsis` | BreadcrumbEllipsis: Tabler Dots, 16px, for the steps left out of a long path. |

## Accessibility

Role: `navigation`

| Keys | Action |
| --- | --- |
| `Tab` | Moves through the links; the current page and the carets are not focusable. |

- The nav is named Breadcrumb, so screen readers list it with the page's landmarks. Pass aria-label to rename it.
- The steps are an ordered list. The current page carries aria-current="page".
- The carets and the ellipsis are decorative and hidden from screen readers. A collapsed path goes in a DropdownMenu whose trigger is named, such as Show the full path.
- The caret turns around in a right-to-left page.

## Install

```bash
npx shadcn add https://werewolf-ui.vercel.app/r/breadcrumb.json
```

This also adds `styles/werewolf.css`, the tokens every component uses, and any other component it needs. Import that file once in your root CSS, after `@import "tailwindcss"`, with a path relative to that CSS file (from `app/globals.css` it is `@import "../styles/werewolf.css"`).