Breadcrumbs
A navigation trail indicator that shows the user's location in the documentation hierarchy.
The Breadcrumbs component displays a horizontal chain of breadcrumb links that indicates the navigation structure of the current active page.
Composable Breadcrumbs Example
Using the primitive Breadcrumbs subcomponents, you can design a custom breadcrumb indicator. The following example shows how to fetch the route segments via useBreadcrumbs and render them with custom icons and separators:
// docs/components/CustomBreadcrumbs.tsx
import React from 'react'
import { Breadcrumbs } from 'boltdocs/primitives'
import { useBreadcrumbs } from 'boltdocs/client'
import { Home } from 'lucide-react'
export default function CustomBreadcrumbs() {
const { crumbs, activeRoute } = useBreadcrumbs()
if (crumbs.length === 0) return null
return (
<Breadcrumbs.Root className="flex items-center gap-2 text-sm font-medium">
{/* 1. Home Base Node */}
<Breadcrumbs.Item>
<Breadcrumbs.Link href="/" className="text-muted hover:text-body transition-colors flex items-center">
<Home size={14} />
</Breadcrumbs.Link>
</Breadcrumbs.Item>
{/* 2. Sibling Nodes */}
{crumbs.map((crumb, idx) => {
const isActive = crumb.href === activeRoute?.path
return (
<Breadcrumbs.Item key={`${crumb.href}-${idx}`} className="gap-2">
<Breadcrumbs.Separator className="text-muted/40" />
<Breadcrumbs.Link
href={crumb.href}
className={isActive
? 'text-body font-semibold cursor-default pointer-events-none'
: 'text-muted hover:text-body transition-colors'
}
>
{crumb.label}
</Breadcrumbs.Link>
</Breadcrumbs.Item>
)
})}
</Breadcrumbs.Root>
)
}
Composable Subcomponents
The Breadcrumbs primitive provides the following subcomponents for structure customization:
| Component | HTML Tag | Description | Props |
|---|---|---|---|
Breadcrumbs.Root / Breadcrumbs | <nav> | The main inline nav wrapper container. | ComponentBaseProps |
Breadcrumbs.Item | <li> | The individual breadcrumb cell container. | ComponentBaseProps |
Breadcrumbs.Link | <a> | An optimized anchor element linking to a parent route category. | Breadcrumbs.Link Props |
Breadcrumbs.Separator | <span> | Renders a directional separation icon (defaults to the Chevron Right icon). | ComponentBaseProps |
Component Props
ComponentBaseProps (Common)
| Property | Type | Default | Description |
|---|---|---|---|
children | ReactNode | undefined | Child content elements. |
className | string | undefined | Custom utility CSS classes. |
style | CSSProperties | undefined | Inline style overrides. |
Breadcrumbs.Link Props
| Property | Type | Default | Description |
|---|---|---|---|
href | string | Required | Target navigation route path. |
className | string | undefined | CSS class style override. |
Breadcrumbs.Separator Props
Inherits ComponentBaseProps plus:
| Property | Type | Default | Description |
|---|---|---|---|
separator | ReactNode | (chevron right) | Custom separator icon/component that replaces the default chevron. |
Customization & states
The Breadcrumbs primitive is style-neutral: it ships the <nav aria-label="Breadcrumb"> landmark with an <ol>/<li> hierarchy and the separator behavior, and every visual decision belongs to the theme through the className passthrough on Breadcrumbs (root), Breadcrumbs.Item, Breadcrumbs.Link, and Breadcrumbs.Separator. It paints no colors itself — current-item styling is driven by the data-current flag the final crumb receives.
| State / Slot | Mechanism |
|---|---|
Breadcrumbs (root) | Renders <nav aria-label="Breadcrumb"> wrapping <ol>; layout and spacing via className |
Breadcrumbs.Item | <li> cell; the final (current) crumb also carries data-current |
| Current crumb | RAC flags the last item: data-current on the <li> and aria-current="page" on the inner link |
Breadcrumbs.Separator | <span> chevron; color and size via className |
Breadcrumbs.Link | Plain router <a>; hover and current colors via className |
<Breadcrumbs className="flex items-center gap-2 text-sm text-muted">
<Breadcrumbs.Item>
<Breadcrumbs.Link href="/" className="hover:text-body transition-colors">
Home
</Breadcrumbs.Link>
</Breadcrumbs.Item>
<Breadcrumbs.Item className="data-current:text-body data-current:font-semibold">
<Breadcrumbs.Separator className="text-muted/40" />
<Breadcrumbs.Link href="/docs/guides" className="hover:text-body transition-colors">
Guides
</Breadcrumbs.Link>
</Breadcrumbs.Item>
</Breadcrumbs>
