# Breadcrumb

A trail of links to the pages above this one. CSS only. (CSS only.)

Reference: https://timeless.build/docs/components/breadcrumb/

> **Choosing between components.** A breadcrumb says where the current page sits in a hierarchy. For moving between siblings at the same level use [Tabs](/docs/components/tabs/), and for a list of pages in a sequence use [Pagination](/docs/components/pagination/).

> **Markup you author.** Give the `<nav>` an `aria-label` — a page can hold several landmarks of the same type, and an unnamed one is indistinguishable from the rest. Author the final crumb as a `<span data-ui-part="current" aria-current="page">` rather than a link: a link to the page you are already on goes nowhere. Author nothing between the crumbs; the separator is drawn.

## Markup

```html
<nav class="ui-breadcrumb" aria-label="Breadcrumb">
  <ol>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/">Documentation</a></li>
    <li data-ui-part="item"><a data-ui-part="link" href="/docs/components/">Components</a></li>
    <li data-ui-part="item"><span data-ui-part="current" aria-current="page">Breadcrumb</span></li>
  </ol>
</nav>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/breadcrumb.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/breadcrumb.css'
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `item` | No | `[data-ui-part~='item']` | One crumb. Use `<li>`; the separator is drawn before every crumb but the first, so nothing is authored between them. |
| `link` | No | `[data-ui-part~='link']` | The link inside a crumb. Use `<a href>`. |
| `current` | No | `[data-ui-part~='current']` | The final crumb, which names the page you are already on. Author it as a `<span>` rather than a link — a link to here goes nowhere — and put `aria-current="page"` on it. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `data-ui-separator` | `chevron` · `slash` | `chevron` | Which glyph is drawn between crumbs. Both are generated content rather than markup, so neither reaches the accessibility tree and neither is yours to author. For any other glyph, set `--ui-breadcrumb-separator` instead of asking for a new value here. |
| `data-ui-density` | `compact` · `normal` | `normal` | Gap between a crumb and its separator. |

## State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through
the selectors below rather than adding your own state classes.

| State | Source | How to express it |
| --- | --- | --- |
| `current` | aria | Author `aria-current="page"` on the final crumb. Timeless never writes it: which page you are on is not something a stylesheet can know. |

## Styling

Root identity: `ui-breadcrumb`.
Required stylesheets: `tokens.css`, `core/breadcrumb.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/breadcrumb.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-breadcrumb-gap` | Gap between a crumb and its separator. |
| `--ui-breadcrumb-separator` | The separator glyph, as a CSS string. Comes from `data-ui-separator`; set it directly for a glyph the attribute does not offer. Keep the `/ ""` alternative text if you redeclare `content` yourself, or the glyph starts being announced. |

Design tokens this component reads (9), global and set at the theme level: `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-fg-subtle`, `--ui-focus`, `--ui-radius-xs`, `--ui-space-1`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) from the ARIA Authoring Practices Guide.

No keyboard behavior of its own, and the APG says so too: a breadcrumb is links in a labelled landmark, and `Tab` is the traversal. Author `<nav>` with an `aria-label`, an `<ol>` inside it, and the final crumb as an unlinked `<span aria-current="page">`. The separator is a `::before` pseudo-element with empty alternative text, so it is drawn but never announced — which is why there is no separator part to author and no `aria-hidden` to remember.

## Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.