# Breadcrumbs

## Overview

The breadcrumbs component presents the current page's position inside a hierarchy as a classless ordered list of links.

It styles a native `<nav aria-label="breadcrumb">` with a direct child `<ol>`. Separators are inserted by CSS, so authors only provide the hierarchy items.

Use nav instead when users need to move between peer destinations. Use pagination when the controls move through paged table results.

## When to use

Use breadcrumbs to show the current page's position within a meaningful hierarchy and link to its ancestors.

## When not to use

Do not use breadcrumbs for peer destinations or paged results; use nav or pagination.

## Usage

```html
<nav aria-label="breadcrumb">
  <ol>
    <li><a href="/docs">Docs</a></li>
    <li><a href="/docs/components">Components</a></li>
    <li><span aria-current="page">Breadcrumbs</span></li>
  </ol>
</nav>
```

Use breadcrumbs when the interface needs to show where the current page sits within a hierarchy.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- BCR-001: Breadcrumbs render as an inline ordered trail with separators inserted by CSS.
- BCR-002: Links use the text accent color by default.
- BCR-003: Separators use the subtle border color by default.
- BCR-004: Separators render as the `chevron_forward` icon.
- BCR-005: The item marked with `aria-current`, or the last item when no item is marked current, uses the default text color.
- BCR-006: The trail can wrap by default.
- BCR-007: Current-location items should be identified with `aria-current` and remain visually distinct from sibling links.
- BCR-008: Comfortable and compact density come from the shared layout tokens for min-height, padding, and gap.
- BCR-009: The component relies on native `nav`, ordered-list, and link structure instead of requiring component-specific classes.
## Accessibility

- Use a native `<nav>` with `aria-label="breadcrumb"`.
- Prefer an ordered list because the sequence communicates hierarchy and current location.
- Keep breadcrumb destinations as real `<a>` elements.
- Use `aria-current="page"` or `aria-current="location"` for the current item.
- Keep `aria-label="breadcrumb"` exactly on the breadcrumb navigation element so the breadcrumb selector activates.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--breadcrumb-color-focus-ring` | `<color>` | Sets --breadcrumb-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-gap` | `<length>` | Sets --breadcrumb-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-min-height` | `<length>` | Sets --breadcrumb-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-padding-block` | `<length>` | Sets --breadcrumb-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-current-color` | `<color>` | Sets the color for the current page crumb; change it when the final crumb should be more or less prominent than links. |
| `--breadcrumb-focus-ring-size` | `<length>` | Sets --breadcrumb-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-font-family-sans` | `Any` | Sets --breadcrumb-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-font-size` | `<length>` | Sets --breadcrumb-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-fill` | `<number>` | Sets --breadcrumb-icon-fill so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-font-family` | `Any` | Sets --breadcrumb-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-grad` | `<number>` | Sets --breadcrumb-icon-grad so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-opsz` | `<number>` | Sets --breadcrumb-icon-opsz so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-size` | `<length>` | Sets --breadcrumb-icon-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-wght` | `<number>` | Sets --breadcrumb-icon-wght so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-line-height` | `<number>` | Sets --breadcrumb-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-link-color` | `<color>` | Sets the default breadcrumb link color; change it to match the navigation context or a contrasting header surface. |
| `--breadcrumb-link-hover-color` | `<color>` | Sets the hover color for breadcrumb links; change it when links need a stronger interactive state than their resting color. |
| `--breadcrumb-separator-color` | `<color>` | Sets the color of separators between crumbs; change it when dividers should recede or align with nearby border tokens. |

## Depends On

- `--color-border-subtle`
- `--color-focus-ring`
- `--color-text`
- `--color-text-accent`
- `--color-text-accent-strong`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--icon-fill`
- `--icon-font-family`
- `--icon-grad`
- `--icon-opsz`
- `--icon-size`
- `--icon-wght`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-focus-ring-size`