A11y Context Breadcrumb

Accessible contextual breadcrumb navigation generated from document headings. The plugin is framework-agnostic, TypeScript-first, and progressively enhances semantic nav, ol, and li markup.

Installation

npm install a11y-context-breadcrumb
pnpm add a11y-context-breadcrumb
yarn add a11y-context-breadcrumb

Usage

import {
  createA11yContextBreadcrumb
} from "a11y-context-breadcrumb";
import "a11y-context-breadcrumb/styles.css";

const root = document.querySelector("[data-a11y-context-breadcrumb]");

if (root instanceof HTMLElement) {
  createA11yContextBreadcrumb(root);
}

Use initA11yContextBreadcrumbAll() when a page has multiple breadcrumb roots. The package does not auto-initialize on import.

CSS

Import a11y-context-breadcrumb/styles.css for baseline layout, sticky positioning, overflow handling, current-item styling, and visible focus states.

Public custom properties include:

• --a11y-context-breadcrumb-bg
• --a11y-context-breadcrumb-color
• --a11y-context-breadcrumb-muted
• --a11y-context-breadcrumb-border
• --a11y-context-breadcrumb-radius
• --a11y-context-breadcrumb-shadow
• --a11y-context-breadcrumb-gap
• --a11y-context-breadcrumb-z
• --a11y-context-breadcrumb-top
• --a11y-context-breadcrumb-font-size
• --a11y-context-breadcrumb-font-size-small

HTML Structure

<nav
  class="a11y-context-breadcrumb"
  aria-label="Current section"
  data-a11y-context-breadcrumb
  data-a11y-context-breadcrumb-content-root="#docs-content"
>
  <ol
    class="a11y-context-breadcrumb__list"
    data-a11y-context-breadcrumb-list
  >
    <li class="a11y-context-breadcrumb__item">
      <span class="a11y-context-breadcrumb__text">Docs</span>
    </li>
  </ol>
</nav>

<main id="docs-content">
  <h2>Forms</h2>
  <h3>Error Summary</h3>
</main>

Headings inside the configured content root become the contextual path. Use data-a11y-context-breadcrumb-label on a heading or section to provide a shorter breadcrumb label, and data-a11y-context-breadcrumb-skip to exclude a subtree.

API

createA11yContextBreadcrumb(root, options) initializes one root and returns an A11yContextBreadcrumb instance.

initA11yContextBreadcrumbAll(options) initializes all [data-a11y-context-breadcrumb] roots in the document.

Instance methods:

• refresh() re-reads headings and rebuilds the path map.
• update(reason, force) updates the active breadcrumb path.
• destroy() removes listeners and plugin-added state.

Key options:

• contentRoot: selector or element containing headings. Defaults to main.
• headingSelector: headings to include. Defaults to h2, h3, h4.
• baseLabel and baseHref: optional leading crumb.
• baseItems: explicit leading crumbs.
• maxItems: maximum rendered crumbs before collapsing the middle.
• sticky, topOffset, and activeOffset: sticky and scroll behavior.
• generateIds: generate missing heading IDs. Defaults to true.
• linkItems and linkCurrent: control rendered links.
• announceChanges: announce the active section in a polite hidden status. Defaults to true.
• includeHiddenHeadings: include hidden headings when needed.
• renderItem: customize individual breadcrumb item rendering.
• onChange: receive active-path changes.

Accessibility Notes

The plugin starts from semantic navigation markup and renders an ordered list of links or text nodes. The current crumb receives aria-current with the configured current value. Breadcrumb links use native anchor keyboard behavior, and default CSS includes a visible :focus-visible style. Active-section changes are mirrored to a visually hidden polite status by default so screen reader users receive concise context updates while scrolling.

When a non-nav root is used, the plugin adds role="navigation" only when no role is already present. Missing heading IDs can be generated for link targets and are removed again by destroy() if the plugin created them.

Examples

• Basic documentation demo
• Lifecycle events studio

Live Demo And GitHub Pages

The repository publishes its static demo and documentation from docs/, while the package artifacts remain in the ignored root dist/ directory.

npm run pages:build

The command builds the package, copies the runtime files that the demo needs into docs/dist/, and generates docs/index.html. Commit the generated docs/ directory with the source changes.

For GitHub Pages, set Settings → Pages → Build and deployment to Deploy from a branch, then choose the main branch and the /docs folder. The published project page is https://vmitsaras.github.io/A11y-Context-Breadcrumb/.

For local package-example work, run npm run build:dist and serve the repository root before opening examples/basic/index.html.

Docs Metadata

import { docs } from "a11y-context-breadcrumb/docs";