Core · Navigation
Breadcrumb
Shows where the page sits in the site, as a trail of links to its parents.
Example
The trail to this page, from Docs to the page you are reading.
The trail at the top of this page is the same component.
Known issues
None known.
Code
Copy the markup
<nav aria-label="Breadcrumb">
<ol class="luz-breadcrumb">
<li><a class="luz-breadcrumb__item" href="/">Home</a></li>
<li><a class="luz-breadcrumb__item" href="/settings/">Settings</a></li>
<li><span class="luz-breadcrumb__item" aria-current="page">Billing</span></li>
</ol>
</nav>Variants and options
There are no modifiers. The separator is drawn by the CSS between two items: there is nothing to write for it.
| Class or attribute | What it does |
|---|---|
.luz-breadcrumb | The ordered list: one row of items, which wraps onto more lines when it is narrow. Each <li> after the first starts with a slash |
.luz-breadcrumb | A parent link, or the current page as text |
aria-current="page" | Marks the current page: primary text colour and medium weight |
How it works
The APG breadcrumb pattern: a <nav> landmark around an ordered list of links, styled by components/breadcrumb.css. No JavaScript.
- The list is ordered because the order is the meaning: screen readers announce a list and its number of items.
- The current page is the last item, a
<span>witharia-current="page", not a link to itself. - The separator is a border drawn by
::beforewith empty content, so assistive technology has nothing to read.
Without JavaScript
Nothing changes: the breadcrumb is a list of links and CSS. Without CSS it reads as a numbered list.
Keyboard and ARIA
Tab reaches each parent link in order; Enter follows it. The current page is not in the tab order.
- Name the
<nav>"Breadcrumb" witharia-label, so it differs from the main navigation. aria-current="page"tells screen readers which item is the current page.
Contrast and focus are in the Design tab.
Design
When to use
Use a breadcrumb when pages sit three or more levels deep, so the reader sees where they are and can go up a level.
When not to use
Do not use a breadcrumb on a flat site, or as the only navigation.
- For the main sections of a site, use a sidebar or a header navigation.
- For steps in a process, show the step number in the page heading instead.
Do and don't
Writing the content
Use the title of each page, shortened if it is long.
- Start at the home or the top of the section.
- End with the current page, as text, not as a link.
Contrast and focus
Links are secondary text; the current page is primary text.
| Part | Colour on background | Light | Dark | High contrast | Needs |
|---|---|---|---|---|---|
Link | --luz-text-secondary on --luz-surface-page | 6.2:1 | 7.5:1 | 19.3:1 | 4.5:1 |
Current page | --luz-text-primary on --luz-surface-page | 15.8:1 | 15.1:1 | 21.0:1 | 4.5:1 |
Separator | --luz-text-muted on --luz-surface-page | 4.9:1 | 5.6:1 | 9.0:1 | 3:1 |
Focus ring | --luz-focus-ring on --luz-surface-page | 5.6:1 | 7.7:1 | 21.0:1 | 3:1 |
Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for focus rings, borders and icons.
- Focus: each link has the shared link ring, a 2 px
--luz-focus-ringoutline 2 px outside the text. - Not colour alone: the current page is not a link, and it is heavier (weight 500).
Tokens it uses
The 6 tokens that components/breadcrumb.css reads, by family. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.
- Spacing and sizing
--luz-space-xs- Typography
--luz-font-sans,--luz-text-sm
Keyboard and ARIA are in the Code tab.