HyBreadcrumb

Usage examples on this page are written for Lit / plain HTML (<hy-breadcrumb>). The same component ships as HyBreadcrumb in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

Child components: <hy-breadcrumb-item> — used only inside this one.

A navigation component that displays a hierarchical breadcrumb trail. Helps users understand their location within a site and navigate back to parent pages.

Key Features

• Semantic HTML structure (nav > ol > li) for accessibility
• Customizable separator via prop (passed to children via CSS custom property), or an icon by name (separator-icon, set on every item)
• Size variants (small, medium, large)
• No separator after the last item — the parent marks it with a [last] attribute (the React HyBreadcrumb draws the same trail: its items hide the separator on :last-child)
• Full WAI-ARIA breadcrumb pattern compliance

Accessibility: built in

• Navigation landmark with aria-label
• Ordered list structure for hierarchy
• Separators hidden from screen readers (aria-hidden)
• Current page marked with aria-current="page"
• Standard keyboard navigation (Tab between links)

Accessibility: your part

• Set current on the last hy-breadcrumb-item, the page you are on.
• Give each breadcrumb its own label when a page has more than one.

Browser Compatibility

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Full SSR compatibility (no hydration mismatches)

SSR Implementation

• Separator text is set on the host as the items' own hook, --hy-breadcrumb-item-separator-content (a container setting its children's hook; an item never reads the breadcrumb's)
• The host CSS variable is inherited by slotted breadcrumb-item children
• Last item is marked with [last] attribute after hydration (handles wrapper-per-item patterns that break CSS :last-of-type)
• Default separator (/) is defined in CSS for SSR before hydration

When to use

• A hierarchy three or more levels deep, where people jump back up: folders, categories, nested settings.

Do

• End with the current page, not a link.
• Use the same names as the pages the items lead to.

When not to use

• A site one or two levels deep: no breadcrumb. The page title and hy-sidebar or hy-topbar already say where you are.
• Steps of a task done in order: hy-stepper.
• Top-level destinations: hy-sidebar or hy-topbar. A breadcrumb only reaches the ancestors of the current page.
• Only one level up to go back to: a single hy-link.

Examples

Basic usage

<hy-breadcrumb>
  <hy-breadcrumb-item href="/">Home</hy-breadcrumb-item>
  <hy-breadcrumb-item href="/products">Products</hy-breadcrumb-item>
  <hy-breadcrumb-item current>Shoes</hy-breadcrumb-item>
</hy-breadcrumb>

With custom separator

<hy-breadcrumb separator="›">
  <hy-breadcrumb-item href="/">Home</hy-breadcrumb-item>
  <hy-breadcrumb-item href="/docs">Documentation</hy-breadcrumb-item>
  <hy-breadcrumb-item current>Components</hy-breadcrumb-item>
</hy-breadcrumb>

With an icon separator

<hy-breadcrumb separator-icon="chevron-right">
  <hy-breadcrumb-item href="/">Home</hy-breadcrumb-item>
  <hy-breadcrumb-item href="/products">Products</hy-breadcrumb-item>
  <hy-breadcrumb-item current>Shoes</hy-breadcrumb-item>
</hy-breadcrumb>

Different sizes

<hy-breadcrumb size="small">...</hy-breadcrumb>
<hy-breadcrumb size="medium">...</hy-breadcrumb>
<hy-breadcrumb size="large">...</hy-breadcrumb>

With home icon

<hy-breadcrumb>
  <hy-breadcrumb-item href="/">
    <hy-icon name="home" slot="prefix"></hy-icon>
    <span class="hy-visually-hidden">Home</span>
  </hy-breadcrumb-item>
  <hy-breadcrumb-item href="/products">Products</hy-breadcrumb-item>
  <hy-breadcrumb-item current>Electronics</hy-breadcrumb-item>
</hy-breadcrumb>

API

Properties

Property	Attribute	Type	Default	Description
separator	separator	string	'/'	The separator displayed between breadcrumb items. Can be any string (e.g., "/", "›", "→"). Set as CSS custom property on the host for inheritance by children. For an icon separator, set separator-icon instead.
separatorIcon	separator-icon	string	''	An icon drawn as the separator, a name from the design system's icon family; set on every item (hy-breadcrumb-item separator-icon), so the trail is the one source. Empty: the text separator.
label	label	string	'Breadcrumb'	Accessible label for the navigation landmark. Announced by screen readers to identify this as breadcrumb navigation.
size	size	'small' | 'medium' | 'large'	'medium'	Size variant affecting font size and spacing. - small: Compact breadcrumbs for dense layouts - medium: Default size for most use cases - large: Larger breadcrumbs for prominent navigation

Slots

Slot	Description
default	Breadcrumb items (hy-breadcrumb-item elements)

CSS Parts

Part	Description
base	The nav element
list	The ordered list (ol) element

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-breadcrumb-list-gap-shell-inline	var(--hy-gap-shell-inline)	Gap between breadcrumb items
--hy-breadcrumb-gap-shell-inline	var(--hy-gap-shell-inline)	Gap between breadcrumb items in print
--hy-breadcrumb-body-sm-font-family	var(--hy-body-sm-font-family)	Font family override for breadcrumb text
--hy-breadcrumb-caption-md-font-family	var(--hy-caption-md-font-family)	Font family override for breadcrumb text
--hy-breadcrumb-body-md-font-family	var(--hy-body-md-font-family)	Font family override for breadcrumb text