Breadcrumb

NavigationSince 0.2.0

import { Breadcrumb } from '@absoluteui/components/breadcrumb';
import '@absoluteui/components/breadcrumb/style.css';

Using Angular? See Breadcrumb for Angular.

What it does

Show where the current page sits in a hierarchy and let users jump to its ancestors. Breadcrumb implements the WAI-ARIA APG Breadcrumb pattern: a labelled <nav> with an ordered list of links, the current page marked with aria-current="page". Long trails can collapse behind an expander. Hrefs are validated (http(s) and relative URLs only), and a cancelable aui-navigate event lets client-side routers take over.

When to use

• Hierarchical sites or apps where users benefit from seeing and jumping to ancestor pages.
• Deep pages reached from search or links, to show where the page sits.

When not to use

• Flat sites with one or two levels.
• Showing browsing history (breadcrumbs show hierarchy, not the path taken).
• Sequential processes: use a stepper.

Examples

Product hierarchy

import { Breadcrumb } from '@absoluteui/components/breadcrumb';

const host = document.createElement('div');
document.body.append(host);
Breadcrumb.create(host, {
  items: [
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Laptops', href: '/products/laptops' },
  ],
});

Collapsed trail with a client-side router

import { Breadcrumb, type BreadcrumbNavigateDetail } from '@absoluteui/components/breadcrumb';

const host = document.createElement('div');
document.body.append(host);
const navigate = (path: string): void => {
  history.pushState(null, '', path);
};
Breadcrumb.create(host, {
  maxItems: 3,
  items: [
    { label: 'Home', href: '/' },
    { label: 'Projects', href: '/projects' },
    { label: 'Atlas', href: '/projects/atlas' },
    { label: 'Settings', href: '/projects/atlas/settings' },
    { label: 'Members' },
  ],
});
host.addEventListener('aui-navigate', (event) => {
  const { item } = (event as CustomEvent<BreadcrumbNavigateDetail>).detail;
  if (item.href !== undefined) {
    event.preventDefault();
    navigate(item.href);
  }
});

Usage

import { Breadcrumb, type BreadcrumbNavigateDetail } from '@absoluteui/components/breadcrumb';
import '@absoluteui/components/breadcrumb/style.css';

const host = document.querySelector<HTMLElement>('#trail');
if (host) {
  Breadcrumb.create(host, { maxItems: 3, items: [{ label: 'Home', href: '/' }, { label: 'Docs', href: '/docs' }, { label: 'API', href: '/docs/api' }, { label: 'Tabs' }] });
  host.addEventListener('aui-navigate', (event) => {
    const { item } = (event as CustomEvent<BreadcrumbNavigateDetail>).detail;
    if (item.href !== undefined) {
      event.preventDefault();
      history.pushState(null, '', item.href);
    }
  });
}

More usage

import { Breadcrumb } from '@absoluteui/components/breadcrumb';

const host = document.createElement('div');
document.body.append(host);
Breadcrumb.create(host, {
  items: [
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Laptops' },
  ],
});

Anatomy

<div class="aui-breadcrumb">                                        (consumer host)
  <nav class="aui-breadcrumb__nav" aria-label="Breadcrumb">
    <ol class="aui-breadcrumb__list">
      <li class="aui-breadcrumb__item"><a class="aui-breadcrumb__link" href="/">Home</a></li>
      <li class="aui-breadcrumb__item aui-breadcrumb__item--collapsed">    (when collapsed)
        <svg class="aui-icon aui-breadcrumb__separator" aria-hidden="true">
        <button class="aui-breadcrumb__expander" aria-label="Show all breadcrumbs"><span aria-hidden="true">...</span></button>
      </li>
      <li class="aui-breadcrumb__item">
        <svg class="aui-icon aui-breadcrumb__separator" aria-hidden="true">
        <span class="aui-breadcrumb__text" aria-current="page">Current</span>
      </li>
    </ol>
  </nav>
</div>

API reference

Factory

Breadcrumb.create(host: HTMLElement, options: BreadcrumbOptions): Breadcrumb

Global configuration key: breadcrumb (see Configuration).

Options

Option	Type	Default	Description
items	readonly { label: string; href?: string }[]		Trail from the root to the current page (last item). Items without href render as text. Required.
label	string	"Breadcrumb (localized)"	Accessible name of the <nav>.
linkCurrent	boolean	false	Render the current (last) item as a link when it has an href.
icons	Partial<{ separator: IconRef }>		Icon slot overrides.
maxItems	number	0	0 never collapses. Otherwise (>= 2), longer trails show the first item, an expander, and the last maxItems - 1 items. Globally configurable.
locale	string	"en-US"	Message locale. Globally configurable. Inherited from common configuration.
direction	'ltr' | 'rtl'	"ltr"	rtl mirrors the separator icon. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	Consumer host; its children are owned by the component.
nav	HTMLElement	The <nav> landmark.
expanded	boolean	Whether the user expanded a collapsed trail.
options	Readonly<BreadcrumbOptions>	Current instance options.

Methods

Method	Description
update(options: Partial<BreadcrumbOptions>): void	Merge and apply options. New items collapse again.
destroy(): void	Remove rendering, listeners, and subscriptions.

Events

Event	Detail	Bubbles	Cancelable	Description
aui-navigate	{ index: number; item: BreadcrumbItem }	Yes	Yes	An unmodified primary click on a link. preventDefault stops native navigation so a router can handle it.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-breadcrumb	Host.
aui-breadcrumb--rtl	Configured rtl direction.
aui-breadcrumb__nav	The <nav> landmark.
aui-breadcrumb__list	The <ol>.
aui-breadcrumb__item	An <li>; –collapsed for the expander item.
aui-breadcrumb__link	Item link.
aui-breadcrumb__text	Text item (current page or no href).
aui-breadcrumb__separator	Decorative separator icon.
aui-breadcrumb__expander	Button that reveals collapsed items.

Icon slots

Slot	Default icon
separator	chevron-right

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-color-focus-ring | --aui-color-hover | --aui-color-link | --aui-color-text | --aui-color-text-muted | --aui-control-height-sm | --aui-focus-ring-offset | --aui-focus-ring-width | --aui-font-family-sans | --aui-font-size-sm | --aui-font-weight-medium | --aui-icon-size-sm | --aui-line-height-normal | --aui-radius-sm | --aui-space-1 | --aui-space-2

TypeScript definitions

interface BreadcrumbItem { label: string; href?: string }
interface BreadcrumbIcons { separator: IconRef }
interface BreadcrumbNavigateDetail { index: number; item: BreadcrumbItem }

Accessibility

Pattern: WAI-ARIA APG Breadcrumb pattern.

Keyboard

Key	Context	Action
Tab / Shift+Tab	Any	Moves between links and the expander button (native tab order).
Enter	Link focused	Follows the link; emits cancelable aui-navigate first.
Enter / Space	Expander focused	Reveals the full trail in place and moves focus to the first revealed item.

Roles

Element	Role
<nav>	navigation (native landmark)
<ol>	list (native)
<a href>	link (native)
expander <button>	button (native)

ARIA attributes

Attribute	Element	Value
aria-label	<nav>	label option or localized ‘Breadcrumb’
aria-current	last item	page
aria-hidden	separator icons, expander ellipsis	true (decorative)
aria-label	expander button	Localized ‘Show all breadcrumbs’

Focus

No focus management except after expanding: focus moves to the first revealed item (made programmatically focusable when it is text), so focus never falls back to the document body.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.3.1 Info and Relationships	A
2.1.1 Keyboard	A
2.4.3 Focus Order	A
2.4.4 Link Purpose (In Context)	A
2.4.7 Focus Visible	AA
2.4.8 Location	AAA
4.1.2 Name, Role, Value	A

Automated test results: Accessibility and compliance.

Notes and known caveats

• The ordered list conveys the number of levels and each item’s position.
• Separators are decorative icons, not text characters, so they are not announced.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

default, hover, focus-visible, current page, collapsed, expanded.

State transitions

From	Trigger	To
collapsed	expander activated	expanded; focus on the first revealed item
expanded	update({ items })	collapsed again when the new trail exceeds maxItems
any	link click	aui-navigate; native navigation unless prevented

Accessibility notes

• The ordered list conveys the number of levels and each item’s position.
• After expanding, focus moves to the first revealed item. A revealed text item gets tabindex="-1" so it can take focus.
• Links are underlined, so they are not distinguished by color alone.
• Manual screen-reader verification is pending (see Known limitations).

Responsive behavior

Items wrap onto multiple lines and long labels break anywhere. Set maxItems to collapse long trails, for example through global configuration on small screens.

Right-to-left

Layout follows the document direction. The chevron separator is mirrored when direction is 'rtl' or when the element is in an rtl context (:dir(rtl)).

Theming

Colors come from role tokens only. Verified in the light, dark, and high-contrast themes. In forced-colors mode links use LinkText and the expander gets a ButtonText border.

Global configuration

configureAbsoluteUI({ components: { breadcrumb: { maxItems: 4 } } });

Changes apply to existing instances immediately.

Component configuration

Instance options override global and theme defaults. All options are dynamic.

Icons

icons.separator (default chevron-right).

Security

Labels use textContent. Each href is parsed with the URL standard against document.baseURI. Only http:/https: URLs and scheme-less URLs (relative, path-absolute, protocol-relative, query, fragment) are accepted, so javascript:, data:, vbscript:, file:, mailto: and obfuscations such as java\tscript: throw BREADCRUMB_OPTIONS. The error names the property but never echoes the value. CSP-safe.

Data handling

No persistence, network access, or telemetry. Navigation is native link navigation unless aui-navigate is prevented.

Performance

One click listener on the list and one configuration subscription per instance. Budget: under 1 ms for Breadcrumb.create with 10 items.

Supported data scale

Trails of any practical depth; collapsing is recommended above about 5 items. Tested with trails of up to 6 items.

Edge cases

• A single-item trail renders one current-page item and no separator.
• maxItems: 2 shows the first item, the expander, and the current page.
• maxItems: 1 is rejected, because it would hide the current page.
• Items without href render as text, including in the middle of the trail.
• With a file: base URL, relative hrefs are still accepted.

Errors

Code	Category	Cause
BREADCRUMB_OPTIONS	configuration	Empty items, an empty item label, an empty label, or an unsafe or unparsable href.
CFG_INVALID_VALUE	configuration	Invalid maxItems, locale, or direction.

A failed construction leaves no rendering, listeners, or subscriptions behind.

Known limitations

• Collapsing is by item count, not by measured width.
• An expanded trail stays expanded until the items change.
• Screen-reader behavior has not yet been manually verified with NVDA, JAWS, and VoiceOver.

Unsupported scenarios

• A dropdown menu of collapsed items (the expander reveals them in place).
• HTML in labels.
• Hrefs with schemes other than http and https.