Breadcrumb « Navigation

The <x-wirekit::breadcrumb> component renders a navigation trail with customizable separators. It follows the WAI-ARIA Breadcrumb pattern.

Usage

Basic Breadcrumb

Home
Products
Widget

<x-wirekit::breadcrumb schema="false" :items="[
    ['label' => 'Home', 'href' => '/'],
    ['label' => 'Products', 'href' => '/products'],
    ['label' => 'Widget']
]" />

The last item is always rendered as the current page (no link, aria-current="page").

Add an icon key to any item to render a decorative glyph before its label (handy for a leading home icon, or a category icon per crumb). The label stays the accessible link text — the icon is aria-hidden and never reaches the structured data.

Breadcrumb with icons

Home
Products
Laptop

<x-wirekit::breadcrumb schema="false" :items="[
    ['label' => 'Home', 'href' => '/', 'icon' => 'home'],
    ['label' => 'Products', 'href' => '/products', 'icon' => 'layers'],
    ['label' => 'Laptop', 'icon' => 'server']
]" />

Items

Each item can be either an associative array or a plain string:

{{-- Full form: label + href --}}
['label' => 'Products', 'href' => '/products']

{{-- Short form: label only (rendered without link) --}}
'Products'

Items without href are rendered as plain <span> (no link, no current indicator unless it's the last item).

Separators

Separator Variants

<x-wirekit::stack gap="sm">
    <x-wirekit::breadcrumb schema="false" :items="[['label' => 'A', 'href' => '/a'], ['label' => 'B', 'href' => '/b'], ['label' => 'C']]" separator="chevron" />
    <x-wirekit::breadcrumb schema="false" :items="[['label' => 'A', 'href' => '/a'], ['label' => 'B', 'href' => '/b'], ['label' => 'C']]" separator="slash" />
    <x-wirekit::breadcrumb schema="false" :items="[['label' => 'A', 'href' => '/a'], ['label' => 'B', 'href' => '/b'], ['label' => 'C']]" separator="arrow" />
    <x-wirekit::breadcrumb schema="false" :items="[['label' => 'A', 'href' => '/a'], ['label' => 'B', 'href' => '/b'], ['label' => 'C']]" separator="dot" />
</x-wirekit::stack>

Value	Character
`chevron` (default)	›
`slash`	/
`arrow`	→
`dot`	·
custom	any string you pass

Structured Data (SEO)

The component automatically renders a Schema.org BreadcrumbList as JSON-LD. Search engines (Google, Bing) use this to display breadcrumb trails directly in search results.

<!-- Rendered automatically — no extra setup needed -->
<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "/" },
        { "@type": "ListItem", "position": 2, "name": "Products", "item": "/products" },
        { "@type": "ListItem", "position": 3, "name": "Widget" }
    ]
}
</script>

Items with an href get the item property (the URL). The last item (current page) typically has no item URL, which is recommended by Google.

Validate your breadcrumbs with Google's Rich Results Test to ensure they appear correctly in search results.

The trail emits its structured data without being asked, which is right for the ordinary case and wrong the moment a page has two breadcrumbs — a shell's top bar and one in the content body. Pass schema="false" on the second:

{{-- 1. The shell's top bar carries the canonical trail, and its structured data. --}}
<x-wirekit::shell-bar>
    <x-wirekit::breadcrumb :items="$trail" />
</x-wirekit::shell-bar>

{{-- 2. A second, visual-only copy in the body. Same trail, no competing JSON-LD. --}}
<x-wirekit::breadcrumb :items="$trail" schema="false" />

Props

Prop	Type	Default	Description
`items`	`array`	`[]`	Array of items; each is `['label' => .., 'href' => .., 'icon' => ..]` or a plain string
`separator`	`string`	`'chevron'`	`'chevron'`, `'slash'`, `'arrow'`, `'dot'`, or any custom string
`schema`	`bool`	`true`	Emit BreadcrumbList JSON-LD for this trail. Turn it off when the page already carries a breadcrumb elsewhere — a shell's top bar plus one in the content body is the common case. A page must carry exactly one BreadcrumbList; two of them compete rather than combine, and a crawler shown two trails for one URL picks one or neither
`scope`	`string\|null`	`null`	Scoped personalization key

Accessibility

Outer <nav aria-label="Breadcrumb"> — the landmark
Semantic <ol> / <li> structure — reads as an ordered list
Last item marked with aria-current="page"
Separators marked aria-hidden="true" so screen readers don't announce "chevron"

Keyboard Interaction

Key	Action
`Tab`	Move focus to the link
`Enter`	Activate the link (follow the URL)

Each crumb is a link with native browser keyboard semantics.

Pitfalls

Don't link the current page in the last crumb. WAI-ARIA Authoring Practices require the trailing crumb to use aria-current="page" and render as plain text — the component already enforces this when the last item omits href.
Don't include more than 5 crumbs. Cognitive overhead spikes; collapse mid-path with an ellipsis crumb.

Design Tokens

Token	Used for
`--font-wk-body-weight`	Item font weight
`--text-wk-sm`	Item font size
`--color-wk-text`	Current page item
`--color-wk-text-muted`	Inactive ancestor links
`--color-wk-text-subtle`	Separator chevron
`--color-wk-ring`	Focus ring
`--ring-wk-width`	Focus ring width
`--radius-wk-sm`	Focus ring radius
`--padding-wk-x-xs`	Item horizontal padding
`--transition-wk-duration`	Hover transition

Config Defaults

The defaults live in config/wirekit.php under components.breadcrumb. Override them globally:

'components' => [
    'breadcrumb' => ['separator' => 'slash'], // change default separator
],