Breadcrumb
Shows where the current page sits in the hierarchy and links back up to each ancestor. The last item is the current page and is not a link.
Basic usage
Install the package:
pnpm add @design-schema/react @design-schema/tokens Import the stylesheet once for the app, then the component:
import '@design-schema/tokens/calm-precise/css';
import '@design-schema/react/index.css';
import { Breadcrumb } from '@design-schema/react'; Examples
Props
3 rows| Prop | Type | Default | Description |
|---|---|---|---|
| items required | array { label: string; href?: string | undefined }[] | — | The trail from root to current page, in order. Every item but the last needs an `href`; an ancestor without one, or with an empty-string `href`, renders as plain text (never an empty link); a plain ancestor has no anatomy part of its own — it is text inside `item` (a `<span>` with no data-part and no class on web and Lit, a Text with no testID on native) and takes `itemColor`; it needs no selector of its own, since the `item` part already selects its container. It renders no interactive element, so activating it fires no `onNavigate`. The last is the current page and its `href` is ignored. An empty array renders the named landmark around an empty list; a single item renders only the current page; neither raises a dev warning. Lit starts the property as `[]`. Export the item type as `BreadcrumbItem`. |
| label | string | Breadcrumb | Accessible name of the navigation landmark. Change it only if the page has another breadcrumb. `copy.navLabel` is the canonical string: the default is that copy key, not a second literal, so translating the copy block moves the default with it. Accessibility: Rendered as aria-label on the nav so it is distinguished from other navigation landmarks. |
| collapse | boolean | true | When there are more than four items, show the first, an ellipsis, and the last two; the ellipsis is a button that reveals the rest. The rule is literal: five items hide the second and third. Once revealed the trail stays expanded for the life of the instance, even if `items` changes. That state is deliberately private: no prop or event exposes it, so it cannot be observed, persisted or reset, and a remount collapses the trail again. Set false for short trails that must always show in full. |
Events
1 row| Event | Type | Description |
|---|---|---|
| onNavigate | onNavigate / navigate | Fired when a non-current item is activated, as `(item, index, event)` on web and `(item, index)` on native, where there is no event. On web the link still navigates unless the handler returns `false` or calls `event.preventDefault()`. On Lit, `preventDefault()` on the `navigate` CustomEvent or on `detail.originalEvent` both cancel (the first also prevents the original click). On native the handler is passed to Link as `onPress` and typed `boolean | void`: it is the navigation, so returning `false` has nothing to cancel (Breadcrumb links are never `external`); without a handler the Link falls back to Linking.openURL. |
Accessibility
Decisions this component leaves to you
Choose the landmark role, and give it a name when the page has more than one landmark of that role.
Supply an accessible name. This component has no text of its own to fall back on, so without one a screen reader announces its role and nothing else.
Implicit ARIA role: navigation.
Anatomy
What generation guarantees
Landmark — It renders a landmark, so assistive technology can jump straight to it.
Accessible name — Every instance carries a programmatic name. Where the component has no text of its own to use, the name is a prop the consumer supplies.
Visible focus — Keyboard focus is always drawn, from the theme’s focus tokens, and is never removed.
Keyboard operable — Everything the pointer can do here, the keyboard can do — see the keyboard section.
Target size — Interactive targets are at least 24×24 CSS pixels (WCAG 2.2 Target Size, minimum).
Contrast — Text and meaningful non-text contrast meets WCAG AA; the pairs are listed below.
This component does not animate, so it has no reduced-motion behaviour to describe.