Breadcrumb
Hierarchical navigation trail showing the current page's position in the site structure. Renders as a semantic <nav> with an ordered list and a customizable divider. On viewports narrower than --breakpoint-xs (480px) the list collapses to a single "← parent" link (the second-to-last item). links is an array of objects with text and optional url. Items without a url render as plain text. By default the last item is rendered as an anchor (with aria-current="page" on the <a>); set use_link_for_active: false to render it as plain text instead, in which case aria-current="page" moves to the <li>.
Usage
When to use
- On pages that sit inside a hierarchy more than one level deep
- On interior content pages to give users context and a route back to the parent
- Inside the hero on pages that use a hero component
When not to use
- On homepages and top-level landing pages
- On pages where the user arrives via a flat navigation pattern (e.g. single-page sites)
- As a substitute for primary navigation
Do
- Use
<ol>because the order is meaningful - Mark the current page with
aria-current="page" - Provide a mobile-compact variant that surfaces the parent link
Don't
- Include the current page as a link unless the page actually navigates somewhere different
- Expose the divider to assistive tech - it is a decorative CSS pseudo-element and must be hidden from the accessibility tree
- Style the
aria-labelas a visible label - it is an accessibility hook only
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
links | array | - | Array of {text, url} link objects. The last item is the current page. |
label | string | Breadcrumb | Accessible name for the navigation landmark. |
use_link_for_active | boolean | true | When true, the last item renders as an anchor with aria-current="page". When false, it renders as plain text. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
Examples
Custom divider
Breadcrumb with an alternate divider character set via --breadcrumb-divider.
Mobile compact
Mobile variant showing only the parent link (← Parent).
Active as text
The current page renders as plain text rather than a link, while still carrying aria-current="page".
Accessibility
- WCAG 2.2 AA
- Container is a
<nav>witharia-label="Breadcrumb". - List is an
<ol>because the order is meaningful. - Current page uses
aria-current="page"on the last item. - Divider is decorative and must not be announced.
- Class is a styling hook only;
aria-labelis the accessibility hook. Data attributes are reserved for JS behavior hooks.