Breadcrumbs
Breadcrumbs show hierarchy navigation with ordered list semantics and current page support.
Overview and decision boundary
Use Breadcrumbs to show the current page position in a hierarchy and provide native anchor links back to parent levels.
Do not use Breadcrumbs as a sidebar, tabs replacement, or command navigation.
Preview
import { Breadcrumbs } from '@nerio-ui/ui';<Breadcrumbs items={[{ label: 'Docs', href: '/docs' }, { label: 'Components', href: '/docs/components' }, { label: 'Button' }]} />Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add breadcrumbsimport { Breadcrumbs } from '@nerio-ui/ui';Usage
import { Breadcrumbs } from '@nerio-ui/ui';<Breadcrumbs items={[{ label: 'Docs', href: '/docs' }, { label: 'Components', href: '/docs/components' }, { label: 'Button' }]} />Variants
| Variant | Purpose |
|---|---|
Default | Single semantic trail with parent links and a current page. |
Anatomy
| Slot | Purpose |
|---|---|
root | Nav landmark with aria-label="Breadcrumb" by default. |
list | Ordered list that preserves hierarchy semantics. |
item | One hierarchy level in the trail. |
link | Native anchor for parent destinations. |
current | Current page item marked with aria-current="page". |
separator | Decorative separator hidden from assistive technology. |
States
| State | Purpose |
|---|---|
Linked parent | Parent items render native anchors. |
Current page | The final item is text with aria-current="page". |
Focus | Linked items use the shared Nerio focus ring. |
Motion
- hover
- focus
Accessibility
- Renders a nav landmark with aria-label="Breadcrumb" by default.
- Uses ordered list semantics for the hierarchy trail.
- Marks the current page with aria-current="page".
- Separators are decorative and hidden from assistive technology.
API
| Prop | Purpose |
|---|---|
items | Array of labels with optional href values and current flags for parent destinations. |
aria-label | Defaults to Breadcrumb and can be customized for local context. |
className | Extends the nav root without replacing tokenized defaults. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | breadcrumbs installs 5 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | None. |
Package dependencies | clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Breadcrumbs to show the current page position in a hierarchy and provide native anchor links back to parent levels.
Do / do not
Do
Use for hierarchical docs, settings, object detail, and nested product pages.
Do not
Do not use Breadcrumbs as a sidebar, tabs replacement, or command navigation.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-breadcrumbs-gap | Public customization point for this component contract. |
--n-breadcrumbs-separator-color | Public customization point for this component contract. |
--n-link-color | Public customization point for this component contract. |
--n-link-color-muted | Public customization point for this component contract. |
--n-motion-hover-duration | Public customization point for this component contract. |
--n-motion-hover-easing | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |