Breadcrumb
Displays the path to the current resource using a hierarchy of links.
Features
- Semantic navigation
- Ordered trail
- Current page state
- Custom separators
- Collapsed paths
- Headless
Installation
npm install @ariaui/breadcrumb
Examples
Three patterns: a default trail with built-in chevron separators, a collapsed middle segment using @ariaui/dropdown-menu, and a custom slash separator.
Styling uses semantic tokens from @ariaui/tokens; adjust className on Link, Page, and Separator as needed.
Default
Navigable links for ancestors and a current page without a link. Separators use the package default chevron when you omit children.
No preview output yet.
Collapsed
Middle segments live in a dropdown behind an ellipsis control, common for deep hierarchies.
No preview output yet.
Custom separator
Pass an icon or text as children of Separator to replace the default chevron—for example a slash.
No preview output yet.
Anatomy
import * as Breadcrumb from "@ariaui/breadcrumb";
export default function Example() {
return (
<Breadcrumb.Root>
<Breadcrumb.List>
<Breadcrumb.Item>
<Breadcrumb.Link />
</Breadcrumb.Item>
<Breadcrumb.Separator />
<Breadcrumb.Item>
<Breadcrumb.Page />
</Breadcrumb.Item>
<Breadcrumb.Item>
<Breadcrumb.Ellipsis />
</Breadcrumb.Item>
</Breadcrumb.List>
</Breadcrumb.Root>
);
}
API Reference
Root
Navigation landmark that wraps the breadcrumb trail. Renders a `<nav>` element.
| Attribute | Values |
|---|---|
| aria-label="breadcrumb" | Default label for the navigation landmark; can be overridden. |
List
Ordered list container for breadcrumb items. Renders an `<ol>` element.
Item
Wraps individual breadcrumb entries (both links and pages). Renders an `<li>` element.
Link
Clickable link for navigable ancestor pages. Renders an `<a>` element.
| Prop | Type | Default |
|---|---|---|
href* | string | — |
Page
Represents the current page — the terminal item in the trail. Renders a `<span>` element.
| Attribute | Values |
|---|---|
| role="link" | Always present on the Page element |
| aria-current="page" | Indicates this is the current page in the breadcrumb trail |
| aria-disabled="true" | Present to prevent interaction; acts as the terminal item |
Separator
Decorative separator between breadcrumb items. Pass custom `children` to override the default chevron icon. Renders an `<li>` element.
| Prop | Type | Default |
|---|---|---|
children | ReactNode | Default chevron icon |
| Attribute | Values |
|---|---|
| role="presentation" | Always present; marks this as a decorative element |
| aria-hidden="true" | Always present; hides the separator from screen readers |
Ellipsis
Collapsed path indicator for long breadcrumbs. Renders a `<span>` with a default ellipsis icon.
| Attribute | Values |
|---|---|
| role="presentation" | Always present; marks this as a decorative element |
| aria-hidden="true" | Always present; hides the ellipsis from screen readers |
Keyboard
| Shortcut | Action |
|---|---|
| Tab | Move focus to the next focusable link element. |
| Shift+Tab | Move focus to the previous focusable link element. |
| Enter | Navigate to the linked page when a Link has focus. |
Accessibility
The Breadcrumb component implements the WAI-ARIA Breadcrumb pattern. The Root renders as a navigation landmark with aria-label="breadcrumb". Links are regular <a> elements, while the current page is marked with aria-current="page" and rendered as a <span> (non-clickable).
Separators
Separators and ellipsis are marked as aria-hidden="true" to avoid redundant screen reader announcements. Provide text alternatives only when necessary for context.