Breadcrumbs
The trail of pages above a nested page, as links above its title.
import { Breadcrumbs } from "@butteryui/react";Demo
When to use it
Use it for
- A page nested under another, such as one plan under Settings and its plans
- Above a PageHeader's title, through its breadcrumbs prop
Not for
- A top-level page: it has no trail
- Steps in a flow: use the flow's own progress, such as PageDots
- Moving between sibling pages: use Tabs or TabNav
Examples
Nested settings page
A nested settings page whose trail leads back up, each crumb opening its page and a top page showing none.
Roaster plan
Billed on the 1st of each month.
Plan trail
The pages above a plan's page, outermost first, with onNavigate where a router takes over each link.
On the Roaster plan page
Trail on a phone
In a narrow column the trail shows only the page one level up, so going back stays one tap away.
Rosa Delgado
Variants and states
A trail
The pages above the one shown, outermost first; the page itself is its title.
On a phone
Under 480px of its own width it shows the page one level up, after a back chevron.
Props
Breadcrumbs
| Prop | Type | Default | Description |
|---|---|---|---|
itemsrequired | readonly BreadcrumbItem[] | The pages above the one shown, outermost first. The page itself is its header's title, not a crumb. | |
label | string | "Breadcrumbs" | Names the navigation for screen readers. Defaults to "Breadcrumbs". |
onNavigate | ((href: string, event: MouseEvent<HTMLAnchorElement>) => void) | Runs as a link is followed, where a router can take over. A click that opens the page elsewhere, in a new tab or window, is left to the browser. |
It also takes ComponentPropsWithRef<"nav">.
BreadcrumbItem
One page in a breadcrumb trail.
| Field | Type | Default | Description |
|---|---|---|---|
labelrequired | string | The page's name, such as "Settings". | |
hrefrequired | string | Where its link goes. |
Accessibility
A navigation landmark named Breadcrumbs (or label) holding an ordered list of links; the chevrons between them are hidden from screen readers. The page itself isn't a crumb: its title is the page header's h1. Each link's target reaches 24px tall.
| Keys | What they do |
|---|---|
| Enter | Follows the link with focus |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It takes the width it's given and keeps the trail on one line, long names truncating with an ellipsis and their full name as a title; under 480px of its own width it shows only the page one level up, after a back chevron. Each link's hit area reaches 24px tall.
Related
See it in the roastery demo's settings.