HyBreadcrumbItem

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

Used inside <hy-breadcrumb> — it only means something as part of it.

An individual breadcrumb item that represents a single level in a navigation hierarchy. Designed to work within an hy-breadcrumb container for proper accessibility and styling.

Key Features

• Renders as link (<a>) when href is provided, span when current page
• Supports disabled state with proper ARIA attributes
• Prefix slot for icons (commonly home icon)
• Separator customization via slot or inherited from parent via CSS custom property
• Full keyboard navigation support

Accessibility: built in

• role="listitem" on the host element for list semantics
• aria-current="page" when marked as current
• aria-disabled for disabled items (only when true)
• Proper link semantics with keyboard activation
• Separator hidden from screen readers

SSR Compatibility

• The role="listitem" attribute is reflected and included in SSR output
• Separator text is inherited via CSS custom property --hy-breadcrumb-item-separator-content; an icon separator is the trail's separator-icon, set on each item
• No separator after the last item: it is hidden via the [last] attribute the parent hy-breadcrumb sets (CSS :last-of-type can't be used — items are wrapped). React's HyBreadcrumbItem, the breadcrumb <ol>'s own <li>, hides it on :last-child — same trail; a standalone item keeps its separator on both sides
• No hydration mismatches when used within hy-breadcrumb

When not to use

• A single link that is not part of a trail: hy-link.

Examples

Basic usage within breadcrumb

<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 icon prefix

<hy-breadcrumb-item href="/">
  <hy-icon name="home" slot="prefix"></hy-icon>
  Home
</hy-breadcrumb-item>

Disabled item

<hy-breadcrumb-item href="/locked" disabled> Locked Section </hy-breadcrumb-item>

External link

<hy-breadcrumb-item href="https://example.com" target="_blank">
  External
  <hy-icon name="external-link" label="opens in a new tab"></hy-icon>
</hy-breadcrumb-item>

API

Properties

Property	Attribute	Type	Default	Description
href	href	string	''	The URL to navigate to when clicked. Omit for current page (renders as span).
target	target	'_blank' | '_parent' | '_self' | '_top'	—	Where to open the link. Only applies when href is provided.
current	current	boolean	false	Marks this item as the current page. Adds aria-current="page" and renders as non-interactive.
disabled	disabled	boolean	false	Disables the breadcrumb item, preventing interaction.
separatorIcon	separator-icon	string	''	The icon drawn as the separator, a name from the design system's icon family. The trail sets it on every item from its own separator-icon (one source for the whole trail); the text separator reaches the item as the --hy-breadcrumb-item-separator-content custom property.
showSeparator	show-separator	boolean	true	Whether to show the separator after this item. Set it to false (as a property — a boolean attribute cannot be turned off from markup) to drop this item's separator, e.g. an item standing on its own or one followed by a control that draws its own divider. Inside hy-breadcrumb the last item's separator is already hidden via the [last] attribute the parent sets, whatever this is.

Events

Event	Detail	Description
activate	—	Fired once when the item is clicked or activated with Enter (the link's native click). Detail: { href: string, originalEvent: MouseEvent }

Slots

Slot	Description
default	The breadcrumb item text content
prefix	Content to display before the label (icons)

CSS Parts

Part	Description
link	The anchor element (when href provided)
current	The span element (when current)
prefix	The prefix slot wrapper
label	The text label wrapper
separator	The separator 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-item-gap-row-nav-md-inline	var(--hy-gap-row-nav-md-inline)	Gap between icon and label
--hy-breadcrumb-item-text-transform	none	Text transform for breadcrumb item
--hy-breadcrumb-item-underline-offset	—	Text underline offset
--hy-breadcrumb-item-motion-transition-hover-duration	var(--hy-motion-transition-hover-duration)	Transition duration for hover and focus state feedback
--hy-breadcrumb-item-motion-transition-hover-easing	var(--hy-motion-transition-hover-easing)	Transition easing for hover and focus state feedback
--hy-breadcrumb-item-separator-content	—	content of the separator between items (a CSS string, '/' unless set)

Methods

focus()

Sets focus on the breadcrumb item link.

Parameters:

• options - Optional focus options

blur()

Removes focus from the breadcrumb item.