Breadcrumbs

Alpha

Accessible breadcrumb navigation. Renders a <nav aria-label> landmark with an ordered list of links, marking the last item aria-current="page". Supports collapsible middle items via maxItems with a keyboard-accessible expand button.

Import

import { Breadcrumbs } from "@compa11y/react";

Usage

Example.tsx

import { Breadcrumbs } from "@compa11y/react";

// Basic
function BasicExample() {
  return (
    <Breadcrumbs
      items={[
        { label: "Home", href: "/" },
        { label: "Products", href: "/products" },
        { label: "Model X" },
      ]}
    />
  );
}

// Custom separator
function CustomSeparator() {
  return (
    <Breadcrumbs
      items={[
        { label: "Home", href: "/" },
        { label: "Docs", href: "/docs" },
        { label: "Breadcrumbs" },
      ]}
      separator="›"
    />
  );
}

// Collapsible (shows first + last two, hides middle behind "…")
function CollapsibleExample() {
  return (
    <Breadcrumbs
      items={[
        { label: "Home", href: "/" },
        { label: "Category", href: "/category" },
        { label: "Sub-category", href: "/category/sub" },
        { label: "Product", href: "/category/sub/product" },
        { label: "Model X" },
      ]}
      maxItems={3}
      ariaLabel="Product breadcrumb"
    />
  );
}

Features

<nav> landmark with aria-label (default: "Breadcrumb")
aria-current="page" automatically applied to the last item
Separators are aria-hidden — purely visual
Collapsible middle items via maxItems with an accessible expand button
Focus moves to the first revealed item after expanding
Optional icon support per crumb (aria-hidden wrapper)
forwardRef support
CSS variable customization

Props

Breadcrumbs component props
Prop	Type	Default	Description
`items`	`BreadcrumbItem[]`	-	Ordered list of crumbs. The last item is treated as the current page (aria-current="page")
`ariaLabel`	`string`	`"Breadcrumb"`	Accessible name for the <nav> landmark
`separator`	`React.ReactNode`	`"/"`	Visual separator between items — string or any React node
`maxItems`	`number`	`0`	Collapse middle items when the trail exceeds this count. 0 = never collapse
`unstyled`	`boolean`	`false`	Remove all inline styles; useful when applying your own CSS

Sub-components

BreadcrumbItem

BreadcrumbItem props
Prop	Type	Default	Description
`label`	`string`	-	Visible text for the crumb
`href`	`string`	-	Navigation target. Omit for the current page (last item)
`icon`	`React.ReactNode`	-	Optional decorative icon rendered before the label (wrapped in aria-hidden)

Keyboard Interactions

Accessibility

All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.

Keyboard shortcuts for Breadcrumbs
Key	Action
`Tab`	Moves focus between breadcrumb links and the expand button
`Enter / Space`	Activates a link or the expand button

CSS Customization

Override these CSS custom properties to customize the appearance.

CSS custom properties for Breadcrumbs
Variable	Description	Default
`--compa11y-breadcrumbs-link-color`	Color of breadcrumb links	`#0066cc`
`--compa11y-breadcrumbs-current-color`	Color of the current page item	`inherit`
`--compa11y-breadcrumbs-separator-color`	Color of the separator	`#999`
`--compa11y-breadcrumbs-separator-padding`	Horizontal padding around each separator	`0.375rem`