Breadcrumbs [Draft]

Breadcrumb component specification

• Breadcrumb component specification
  • Owned by
    • Requires approval from:
    • Signed off by:
    • Revision history
  • Overview
    • Key Features
    • Acceptance criteria
  • User stories
    • End-user stories
    • Developer stories
  • Functionality
    • End-user experience
    • Developer experience
      • Basic initialization
      • Customizing the default separator
      • Overriding the separator for a single item
      • Prefix and suffix content
      • Programmatic control
    • Localization
    • Keyboard interactions
  • API
    • Properties and attributes
    • Methods
    • Events
    • Slots
    • CSS Shadow parts
    • CSS Custom Properties
  • Test scenarios
    • Rendering and Initialization
    • Separator Behavior
    • Current Page Marking
    • Slotted Content
    • Accessibility
    • RTL Support
    • Edge Cases
  • Accessibility
    • ARIA roles and properties
    • Keyboard support
    • Right to Left support

Owned by

Team name: TBD

Developer name: TBD

Designer name: TBD

Requires approval from:

TBD

Signed off by:

TBD

Revision history

#	Author	Date	Description
1	Radoslav Karaivanov	2026-08-04	Initial draft

Overview

The igc-breadcrumbs component is a navigation container that renders an ordered trail of igc-breadcrumb items, separated by a configurable icon. It communicates a user's location within a site's hierarchy and provides a way back to higher-level pages.

The pair of elements is suitable for a variety of navigation scenarios such as:

• File browsers: current folder path from the root down to the active folder
• E-commerce: category > subcategory > product navigation trail
• Multi-step wizards or nested content: showing the current section within a larger structure
• Admin dashboards: current location within a nested menu structure

Key Features

• Two composable elements: a igc-breadcrumbs container that manages shared state and a igc-breadcrumb item that renders arbitrary slotted content (typically a link)
• Default separator icon configurable on the container and automatically propagated to every item via context
• Per-item separator override through a dedicated slot
• Current page marking through a boolean property that reflects aria-current="page"
• Prefix and suffix slots on each item for supplementary content (icons, badges, etc.)
• Automatic hiding of the trailing separator on the last item
• Accessibility-first: renders the ARIA list/listitem pattern and mirrors the separator icon in RTL layouts
• Themeable through CSS custom properties and shadow parts

Acceptance criteria

• The container must render its slotted igc-breadcrumb children with the ARIA list role, and each item must expose the listitem role.
• The container must expose a separator property/attribute that sets the default separator icon used by all descendant items.
• An individual item must be able to override the separator through a separator slot.
• The separator must not be rendered after the last item in the trail.
• An item must be able to mark itself as the current page through a current property/attribute, reflecting aria-current="page" on the host.
• An item must support prefix and suffix slots for supplementary content around its main content.
• The elements must be integrated and themeable with the theming mechanism of the library.
• The elements must be WAI-ARIA compliant, following the breadcrumb navigation pattern.
• The separator icon must be mirrored automatically in RTL layouts without additional configuration.

User stories

End-user stories

As an end-user, I expect to be able to:

• see a trail of links representing the path from a top-level page down to the page I am currently viewing.
• see a visual separator between each item in the trail.
• identify which item in the trail represents the page I am currently on.
• navigate back to any of the higher-level pages by activating its link.

Developer stories

As a developer, I expect to be able to:

• slot arbitrary content, typically a link, inside each breadcrumb item.
• control the default separator icon used across all items in a trail.
• override the separator icon or content for an individual item.
• mark an item as the current page and be able to read that state back.
• slot prefix and/or suffix content, such as icons, around an item's main content.
• wrap the trail in a <nav> landmark with an application-provided accessible label.

Functionality

End-user experience

Design Hand-off

The breadcrumb trail presents a clear, horizontal (wrapping) row of items:

• Each item renders its slotted content, typically a link, followed by a separator icon.
• The item representing the current page is visually distinguished (non-interactive, different color) via the current state, and — being the last item in the trail — is not followed by a separator.
• In Right-to-Left layouts, the separator icon is mirrored automatically.
• Screen readers announce the trail as a list, its items, and the current page through aria-current="page".

Developer experience

The igc-breadcrumbs and igc-breadcrumb elements are designed for ease of integration with a declarative API — the container manages the shared separator state, while items are free to render arbitrary slotted content.

Basic initialization

<nav aria-label="Breadcrumb">
  <igc-breadcrumbs>
    <igc-breadcrumb>
      <a href="/home">Home</a>
    </igc-breadcrumb>
    <igc-breadcrumb>
      <a href="/home/category">Category</a>
    </igc-breadcrumb>
    <igc-breadcrumb current>
      <a href="/home/category/item">Item</a>
    </igc-breadcrumb>
  </igc-breadcrumbs>
</nav>

Customizing the default separator

<igc-breadcrumbs separator="chevron_right">
  <igc-breadcrumb><a href="/home">Home</a></igc-breadcrumb>
  <igc-breadcrumb current><a href="/home/item">Item</a></igc-breadcrumb>
</igc-breadcrumbs>

Overriding the separator for a single item

<igc-breadcrumb>
  <a href="/home">Home</a>
  <span slot="separator">/</span>
</igc-breadcrumb>

Prefix and suffix content

<igc-breadcrumb>
  <span slot="prefix">🏠</span>
  <a href="/home">Home</a>
</igc-breadcrumb>

Programmatic control

const items = document.querySelectorAll('igc-breadcrumb');

// Move the "current" marker to the last item after a client-side navigation
for (const item of items) {
  item.current = false;
}
items[items.length - 1].current = true;

Localization

The breadcrumb elements do not contain any built-in text content that requires localization. The nav landmark's aria-label and the slotted link text are provided by the consuming application.

Keyboard interactions

The elements do not implement custom keyboard handling. Navigation relies on the native behavior of the slotted interactive content:

Key	Description
Tab / Shift + Tab	Moves focus between the interactive elements (typically links) slotted into each breadcrumb item.
Enter / Space	Activates the currently focused link, following the native behavior of the slotted element.

API

Properties and attributes

igc-breadcrumbs:

Name	Attribute	Reflects	Type	Default	Description
separator	separator	Yes	string	'tree_expand'	The icon name used as the default separator between breadcrumb items.

igc-breadcrumb:

Name	Attribute	Reflects	Type	Default	Description
current	current	Yes	boolean	false	Marks this breadcrumb as representing the current page.

Methods

None.

Events

None.

Slots

igc-breadcrumbs:

Name	Description
(default)	Default slot for the breadcrumb items.

igc-breadcrumb:

Name	Description
(default)	The main content of the breadcrumb, typically an anchor (<a>) element.
prefix	Renders content before the main breadcrumb content.
suffix	Renders content after the main breadcrumb content.
separator	Overrides the default separator icon rendered after the breadcrumb item.

CSS Shadow parts

igc-breadcrumb:

Name	Description
label	The container wrapping the prefix, default, and suffix slots.
separator	The container wrapping the separator slot content.

CSS Custom Properties

igc-breadcrumbs:

Name	Description
--ig-breadcrumbs-gap	The gap between breadcrumb items. Defaults to 0.5rem.

igc-breadcrumb:

Name	Description
--ig-breadcrumb-link-color	The color of the breadcrumb link. Defaults to --ig-primary-500.
--ig-breadcrumb-link-color-hover	The hover color of the breadcrumb link. Defaults to --ig-primary-700.
--ig-breadcrumb-current-color	The color of the active (current) breadcrumb link. Defaults to --ig-gray-900.
--ig-breadcrumb-separator-color	The color of the separator. Defaults to --ig-gray-500.

Test scenarios

Rendering and Initialization

1. Default rendering
   • The container renders its slotted items with the list ARIA role
   • Each item renders with the listitem ARIA role
   • The default separator icon (tree_expand) is used when separator is not set
2. Passes the accessibility audit
   • The container and its items pass the @open-wc/testing accessibility audit

Separator Behavior

3. Default separator propagation
   • Setting separator on the container updates the icon rendered by every descendant item
   • Changing separator at runtime updates all items reactively
4. Per-item override
   • Content slotted into an item's separator slot replaces the default icon for that item only
5. Trailing separator
   • The separator is hidden for the last item in the trail
   • The separator remains visible for all other items

Current Page Marking

6. current property
   • Defaults to false for a newly created item
   • Reflects as the current attribute when set to true
   • Toggling the property at runtime updates the attribute and the rendered state
7. aria-current
   • Setting current to true sets aria-current="page" on the item
   • Setting current back to false removes aria-current

Slotted Content

8. Default slot
   • Arbitrary content (links, spans, etc.) slotted into an item renders correctly
9. Prefix and suffix slots
   • Content slotted into prefix renders before the default slot content
   • Content slotted into suffix renders after the default slot content

Accessibility

10. ARIA roles and properties
    • The container has role="list"
    • Each item has role="listitem"
    • aria-current="page" is present only on the item marked as current
11. Screen reader support
    • Screen readers announce the trail as a list and its items
    • The current page is announced as such

RTL Support

12. Right-to-Left
    • The separator icon is mirrored when the component is rendered in an RTL context

Edge Cases

13. Empty or single-item trail
    • A container with a single item renders without a separator
    • A container with no items renders without errors
14. Missing slot content
    • An item with no slotted content does not break rendering

Accessibility

ARIA roles and properties

Following the breadcrumb navigation pattern, the following ARIA properties must be present:

• igc-breadcrumbs must have an ARIA role of list.
• igc-breadcrumb must have an ARIA role of listitem.
• igc-breadcrumb must have aria-current="page" when its current property is true.
• Consuming applications should wrap igc-breadcrumbs in a <nav aria-label="..."> landmark to provide an accessible navigation label — the label belongs on the <nav>, not on the list, per the ARIA breadcrumb pattern.

Keyboard support

Not applicable. The elements do not manage focus or intercept keyboard input; navigation relies entirely on the native behavior of the slotted interactive content (e.g. anchors).

Right to Left support

The breadcrumb elements should work in a Right-to-Left context without additional setup or configuration — the default separator icon is mirrored automatically.