Breadcrumb - Canvas Design System

When to Use

Use when: The page sits two or more levels deep in a real hierarchy readers navigate — a workshop inside a category inside the library. Breadcrumbs answer "where am I" and "how do I get back up".

Don't use when: The page is top-level, or the "hierarchy" is really a linear flow — a wizard needs Progress, not a trail. Don't use it to record how the reader arrived; it reflects structure, not history.

Variants

There's one visual treatment. What changes is depth — and the only structural rule is that the final item has no href, because it's the page you're on.

Two levels

Three levels

<?= ws_breadcrumb([
    ['label' => 'Home', 'href' => '/'],
    ['label' => 'Workshops', 'href' => '/library/workshops/'],
    ['label' => 'Design Sprint'],
]) ?>

Deep nesting

Four levels is the practical ceiling. Past that, shorten the labels or reconsider the information architecture — the trail wraps and stops being scannable.

Custom separator

Any Material icon name works. Change it only for a deliberate reason — the chevron is the platform default and consistency is worth more than novelty.

<?= ws_breadcrumb($items, ['separator' => 'arrow_forward_ios']) ?>

States

State	Behavior
Ancestor link	Rendered as an `<a class="ws-breadcrumb__link">` in `--text-muted`.
Hover	Link shifts to `--mainsite-primary` over `--transition-fast`.
Focus	Native browser focus ring on the anchor — the component adds no custom outline.
Current page	The last item is emitted as `<span class="ws-breadcrumb__text">` inside an item marked `.ws-breadcrumb__item--current`, carrying `aria-current="page"`. It's deliberately not a link.
Item with no `href`	Any item can omit `href`, not just the last — it renders as plain text. Use this for a real but unlinkable tier, such as a grouping that has no index page.

Real-World Usage

A library exercise page builds the trail from the record's own category, so the breadcrumb tracks the data rather than being hand-written per page.

<?= ws_breadcrumb([
    ['label' => 'Home',      'href' => '/'],
    ['label' => 'Exercises', 'href' => '/library/exercises/'],
    ['label' => $ex['category_name'],
     'href'  => '/library/exercises/?category=' . urlencode($ex['category_slug'])],
    ['label' => $ex['name']],
]) ?>

Options

Option	Type	Default	Purpose
`$items`	array	required	Positional. Ordered list of `['label' => …, 'href' => …]`, root first. Omit `href` on the last item.
`separator`	string	`'chevron_right'`	Material icon name rendered between items
`id`	string	`null`	Element ID
`class`	string	`''`	Additional CSS classes

Item options

Key	Type	Default	Purpose
`label`	string	—	Visible text. Keep it to the noun — "Exercises", not "All exercises in the library".
`href`	string	`null`	Destination. Omit to render the item as plain text.

Accessibility

This is one of the better-wired components in the set — it follows the WAI-ARIA Breadcrumb pattern as shipped.

Concern	Behavior
Landmark	Wrapped in `<nav aria-label="Breadcrumb">`, so it's reachable as a named landmark and distinguishable from other navs on the page.
Structure	An ordered `<ol>`, so screen readers announce position and count — "3 of 4".
Current page	The final item carries `aria-current="page"` and is not a link, so it isn't announced as an actionable destination.
Keyboard	Ancestor links are standard anchors in `Tab` order, activated with `Enter`. Nothing custom.
Separators	Decorative icons between items. Keep them out of the accessible name — never encode meaning in the separator alone.
Contrast	Ancestors use `--text-muted` against the page surface; the current item uses `--text-dark`. The current item is intentionally the highest-contrast element.

Tokens

Token	Used for
`--text-muted`	Ancestor link colour
`--text-dark` / `--text-default`	Current-page text
`--mainsite-primary`	Link hover colour
`--gray-400`	Separator icon
`--space-1`	Gap between item, separator, and next item
`--text-body` / `--text-meta`	Label type scale
`--font-body` / `--font-medium`	Face, and the weight bump on the current item
`--transition-fast`	Link hover

CSS Classes

Class	Purpose
`.ws-breadcrumb`	The `<nav>` wrapper
`.ws-breadcrumb__list`	The `<ol>`
`.ws-breadcrumb__item`	Each `<li>`
`.ws-breadcrumb__item--current`	The final item
`.ws-breadcrumb__link`	Ancestor anchor
`.ws-breadcrumb__text`	Non-link label (current page, or any item without `href`)
`.ws-breadcrumb__separator`	Separator icon

Files

File	Purpose
`includes/components/helpers.php`	`ws_breadcrumb()` helper function
`includes/components/breadcrumb.php`	Template — list markup and ARIA wiring
`includes/components/components.css`	Styles (`.ws-breadcrumb` rules)