# Breadcrumb

> A trail of links from the top of the site to the current page, in a labeled nav.

- Name: `breadcrumb`
- Status: beta
- Categories: navigation
- File: the install writes `breadcrumb.tsx` to your `ui` alias, `@/components/ui` by default.
- Gallery: https://arbokui.com/components/breadcrumb
- Registry item: https://arbokui.com/r/breadcrumb.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/breadcrumb
   ```

## Use it for

- Showing where a page sits in a deep hierarchy, so people can go up a level in one click.
- Put it at the top of the page, above the page heading.
- End with BreadcrumbPage for the current page. It is not a link, and it carries aria-current="page".
- Put a BreadcrumbSeparator between items, never after the last one.
- For a long trail, keep the first and last two levels and put a BreadcrumbEllipsis in place of the middle.
- With a router, pass its link as render: \<BreadcrumbLink render={\<Link href="/docs" />}>Docs\</BreadcrumbLink>.

## Avoid it for

- Flat sites one level deep. The main navigation already says where people are.
- Showing the steps of a flow, like checkout. Use StepDots or a list of steps instead.
- Replacing the main navigation. A breadcrumb shows the path to this page only.
- Two navs named "Breadcrumb" on one page. Pass a different aria-label to each.

## Props

- `aria-label`: `string`. Default `"Breadcrumb"`. On Breadcrumb. The landmark's name. Rename it when a page has more than one. Left off when you pass aria-labelledby.
- `label`: `string`. Default `"More pages"`. On BreadcrumbEllipsis. What screen readers hear in place of the dots.
- `Breadcrumb`: `Omit<ComponentProps<"nav">, "color">`. The landmark. A \<nav> with aria-label="Breadcrumb". Pass aria-label or aria-labelledby to rename it.
- `BreadcrumbList`: `Omit<ComponentProps<"ol">, "color">`. Part. The ordered list. It wraps on narrow screens.
- `BreadcrumbItem`: `Omit<ComponentProps<"li">, "color">`. Part. One level. Holds a BreadcrumbLink, a BreadcrumbPage, or a BreadcrumbEllipsis.
- `BreadcrumbLink`: `Omit<ComponentProps<"a">, "color"> & { render?: ReactElement }`. Part. A link to a level above. render swaps the \<a> for your own element, like a router link, with the same props and classes.
- `BreadcrumbPage`: `Omit<ComponentProps<"span">, "color">`. Part. The current page, as text with aria-current="page".
- `BreadcrumbSeparator`: `Omit<ComponentProps<"li">, "color">`. Part. The mark between items, a chevron by default. Pass children to use another mark, like "/".
- `BreadcrumbEllipsis`: `Omit<ComponentProps<"span">, "children" | "color"> & { label?: string }`. Part. Three dots for levels left out. label is what screen readers hear. Default "More pages".
- `className`: `string`. Extra classes on any part. Later classes win, so className='text-base' on BreadcrumbList replaces the text size.

## Accessibility

- Breadcrumb renders a \<nav> named "Breadcrumb", so screen readers list it with the page's landmarks.
- The levels are an \<ol>, so screen readers say how many there are and where each one is.
- Separators are \<li role="presentation" aria-hidden="true">. Screen readers skip them, and they are left out of the item count.
- BreadcrumbPage carries aria-current="page" and is not a link, so the current page is not a tab stop.
- BreadcrumbEllipsis has visually hidden text, "More pages" by default, so the gap is not silent. Its dots are aria-hidden.
- The ellipsis is not interactive. If people need the hidden levels, put it inside a button that opens a menu of them.
- Links use muted-foreground and the current page uses foreground. The theme tests hold both to 4.5:1 on the page and on cards.
- Links show the shared focus ring, which the theme tests hold to 3:1.

## Examples

### A trail to the current page

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/settings">Settings</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Billing</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### With Next.js links

```tsx
import Link from "next/link";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink render={<Link href="/" />}>Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Docs</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### A long trail with the middle left out

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/team">Team</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Members</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

### Slashes between items

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>/</BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbPage>Install</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```