registry:ui · NativeHTML
breadcrumb — the trail the platform already defines
nav[aria-label] wrapping an ol of ordinary links, composed part by part: the list carries the order, Link is a real href, Page marks aria-current=page, Separator is pure decoration — no roles to maintain. Long trails fold by WRAPPING the middle items in BreadcrumbCollapse; one node can open a menu of peer pages (BreadcrumbDropdown) — every destination a real anchor.
$npx jixoai-ui add breadcrumb
https://ui.jixoai.com/r/breadcrumb.json
overview
Overview
The root owns nothing but the landmark; eight parts compose the trail, the fold, and the sibling jump.
Breadcrumb is composition-first: the root renders the nav landmark and nothing else — the
old closed crumbs[] data prop died. You author an ordered list directly: a
BreadcrumbList (the ol — its document order IS the hierarchy) of BreadcrumbItem steps,
each holding a BreadcrumbLink, the BreadcrumbPage, or a BreadcrumbSeparator.
Two behaviors are opt-in parts, not props. BreadcrumbCollapse wraps the middle items of a
long trail: they self-hide (the platform hidden attribute) and a single
"…" link stands in, pointing at the first hidden page — never a dead ellipsis.
BreadcrumbDropdown is one trail node that opens a menu of peer destinations; every entry
is a real anchor, so middle-click, reload and crawlers stay honest.
The semantics are the platform's: nav[aria-label] + ol + a[aria-current="page"] — no microdata obligations, no roles to maintain. For the axis grammar, see the universal props concept page.
usage
Usage
Author the ordered list directly; the ol order is the hierarchy and the current page remains a real page part.
<script lang="ts">
import {
Breadcrumb,
BreadcrumbList,
BreadcrumbItem,
BreadcrumbLink,
BreadcrumbPage,
BreadcrumbSeparator,
BreadcrumbCollapse,
BreadcrumbDropdown,
} from '@ui/breadcrumb/index';
</script>
<!-- the trail is authored, not passed as data; the ol's order IS the hierarchy -->
<Breadcrumb>
<BreadcrumbList>
<BreadcrumbItem><BreadcrumbLink href="/">registry</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbItem><BreadcrumbSeparator /></BreadcrumbItem>
<BreadcrumbItem>
<BreadcrumbPage href="/docs/components/breadcrumb.html">breadcrumb</BreadcrumbPage>
</BreadcrumbItem>
</BreadcrumbList>
</Breadcrumb>
<!-- long trails: wrap the middle in BreadcrumbCollapse — the folded
items self-hide and the ellipsis links to the first hidden page -->
<BreadcrumbCollapse>
<BreadcrumbItem><BreadcrumbLink href="/2">page 2</BreadcrumbLink></BreadcrumbItem>
</BreadcrumbCollapse>
<!-- sibling jump: one node opens a menu of peer pages — REAL anchors,
the current one marked, selection dismisses and navigates -->
<BreadcrumbItem>
<BreadcrumbDropdown
label="components"
current="/docs/components/breadcrumb.html"
items={[
{ label: 'tabs', href: '/docs/components/tabs.html' },
{ label: 'breadcrumb', href: '/docs/components/breadcrumb.html' },
]}
/>
</BreadcrumbItem>api
Props
The root carries the landmark label and forwards the eight-axis surface (the shared Universal props section below); the parts keep the trail structure explicit. The composed dropdown-menu inside BreadcrumbDropdown is documented on its own page.
Breadcrumb
| Property | Type | Default | Description |
|---|---|---|---|
| label | string | 'Breadcrumb' | Accessible name of the navigation landmark. |
| children * | Snippet | — | The composed trail — a BreadcrumbList of Items. |
| ...rest | HTMLAttributes | spread | Forwarded to the nav element. |
Universal props
| Property | Type | Default | Description |
|---|---|---|---|
| size | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | the base scale — root font-size; parts size in em |
| shape | 'round' | 'scoop' | 'bevel' | 'notch' | 'square' | 'squircle' | 'auto' | 'auto' · ambient scope | corner geometry (CSS corner-shape; §14 degrade table) |
| radius | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | corner size; auto = the concentric broadcast (§3) |
| density | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | spacing/leading scale over the kernel channels (§4) |
| color | 'primary' | 'secondary' | 'error' | 'warn' | 'success' | 'info' | 'auto' | number | string | 'auto' · ambient scope | the hue axis of the fixed oklch primary system (§5) |
| theme | 'light' | 'dark' | 'system' | 'auto' | 'auto' · ambient scope | light/dark profile; system = the JS-mutable global (§6) |
| elevation | 'level-1' | 'level0' | 'level1' | 'level2' | 'level3' | 'level4' | 'level5' | 'auto' | number | 'auto' · ambient scope | official M3 levels over the surface ladder (§7) |
| motion | 'reduced' | 'subtle' | 'normal' | 'expressive' | 'auto' | number | 'auto' · ambient scope | intensity across the motion kernels (§8) |
BreadcrumbList / BreadcrumbItem
| Property | Type | Default | Description |
|---|---|---|---|
| children * | Snippet | — | List: the Items, Separators and folds, in order (renders the ol, role="list"). Item: one step's content (renders the li); self-hides inside a BreadcrumbCollapse. |
| ...rest | HTMLAttributes | spread | Forwarded to the ol / li element. |
BreadcrumbLink / BreadcrumbPage
| Property | Type | Default | Description |
|---|---|---|---|
| href | string | Link: required · Page: optional | Destination. Without one, Page renders the span form of the same semantics (aria-current stays). |
| child | Snippet | — | Link only — replacement-element escape; receives the merged anchor props ({ class, href, ...rest }); the consumer owns the element. |
| children * | Snippet | — | The visible label. |
| aria-current | "page" | Page only | BreadcrumbPage marks the current destination; not overridable. |
| ...rest | HTMLAnchorAttributes | spread | Forwarded to the anchor element. |
BreadcrumbSeparator / BreadcrumbEllipsis / BreadcrumbCollapse
| Property | Type | Default | Description |
|---|---|---|---|
| children | Snippet | — | Separator only — REPLACES the chevron glyph (data-glyph="custom", aria-hidden stays). Ellipsis renders its own "…"; Collapse renders the fold's ellipsis link. |
| href | string | Collapse only, optional | Where the fold's ellipsis points. Without one it derives the first hidden page's href from its own DOM on hydrate. |
| ...rest | HTMLAttributes | spread | Forwarded to the span / li element; all three are aria-hidden or wrap hidden content. |
BreadcrumbDropdown
| Property | Type | Default | Description |
|---|---|---|---|
| label * | string | — | The trail label on the trigger — the section this node stands for. |
| items * | { label, href }[] | — | Peer destinations offered in the menu — every entry a REAL anchor. |
| current | string | — | href of the current page among the items: aria-current=page + the you-are-here paint. |
| density | Density | ambient scope | The part's own density opinion (the legacy local spelling), feeding the composed menu — explicit ?? inherited. |
a11y
Accessibility
Native navigation landmark, ordered list, links, and aria-current carry the full semantics. In the dropdown menu, the keyboard walk's highlight is a paint-only data attribute — aria-current on the current entry is never rewritten by the walk, so the you-are-here marker survives navigation with its semantics intact.
Keyboard
| Key | Action |
|---|---|
| Tab | Moves through the trail links and the sibling-jump trigger in list order; the trail never steals focus |
| Enter / Space | Opens the sibling-jump menu from the trigger; Enter on a menu entry dismisses the panel, returns focus to the trail node, and navigates |
| Arrow keys | Inside the open menu: arrows move, typeahead jumps, Home/End bound the walk (the dropdown-menu contract) |
ARIA
| Attribute | Value | Description |
|---|---|---|
| aria-label | 'Breadcrumb' | Names the navigation landmark — announced before the trail. |
| aria-current | 'page' | Marks the current trail destination — and the current entry inside the dropdown menu (never touched by the menu walk’s highlight). |
| aria-hidden | 'true' | Hides decorative separators and manual ellipses — screen readers hear the label and the links, not the gaps. |