Breadcrumb

A server-rendered, semantically-tagged trail of ancestor links. The compositional API mirrors the shadcn surface so consumers swap drop-in, and `BreadcrumbLink` keeps a server-safe `asChild` seam (`React.cloneElement`, NOT Base UI `useRender`) so the whole…

navigationserver≥ 480pxuiv1.1.0

Breadcrumb — live renderprimitives-breadcrumb--variants ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/breadcrumb.json

With the @interlace alias

npx shadcn@latest add @interlace/breadcrumb

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Keyboard path

apps/storybook/src/stories/primitives/Breadcrumb.stories.tsx ↗

3 steps, 1 key press — replayed on every PR by the play function of KeyboardFlow. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.

1The trail is a named navigation landmark
2Only the ancestors are navigable
3Tab walks the ancestors in document orderTab

Measured contrast

packages/ui/__tests__/theme-contract-lock.test.ts ↗

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is muted-foreground on background at 7.82:1 (harbor · light), against a floor of 4.5:1.

Measured WCAG contrast ratios per token pair and theme
Pair	interlacelight	interlacedark	harborlight	harbordark	Floor
muted-foreground on backgroundsecondary copy	9.41:1	11.32:1	7.82:1	9.52:1	4.5:1SC 1.4.3
muted-foreground on cardsecondary copy in a card	9.41:1	10.48:1	8.25:1	8.64:1	4.5:1SC 1.4.3
foreground on backgroundbody copy	19.65:1	16.97:1	17.74:1	16.19:1	4.5:1SC 1.4.3

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

Text equivalent

packages/ui/src/primitives/breadcrumb.tsx ↗

A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.

Label, not a data equivalentShips sr-only copy

Ships sr-only copy for what the visual carries by position, colour or icon alone — a label, not a full data equivalent.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary: server component
Renders during SSR / RSC with no hydration cost. It can be imported from a server component without pulling the page into the client.
Minimum viewport: MIN_VIEWPORT = 480
Declared, not assumed. Below 480 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
Coverage gate: 100% × 4
Inside the v8 gate: lines 100, statements 100, functions 100, branches 100. A threshold under 100 only records how much you stopped caring, so there isn't one.

History

This component is at v1.1.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

@interlace/ui 1.0.01 entry

Addedminor
The component floor reaches every tier: form, overlay, navigation and display primitives were modelled to the portable 26-rule floor with skeletons, locked breakpoints, and AA contrast measured per composite rather than eyeballed.
Components

Import

8 named exports — pull the parts you need.

Public API

import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, MIN_VIEWPORT } from '@/components/ui/breadcrumb';

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

BreadcrumbProps

Also accepts every <nav> attribute.

BreadcrumbListProps

Also accepts every <ol> attribute.

BreadcrumbItemProps

Also accepts every <li> attribute.

BreadcrumbLinkProps

Also accepts every <a> attribute.

Prop	Type	Description
asChild	boolean	Render as the passed child element (e.g. `<Link href="…">`) — useful when composing with a routing primitive. Server-safe slot: we `cloneElement` the single React element child and merge our data-slot + className onto it. NOT Base UI useRender (which would flip this tree to client).

BreadcrumbPageProps

Also accepts every <span> attribute.

BreadcrumbSeparatorProps

Also accepts every <li> attribute.

BreadcrumbEllipsisProps

Also accepts every <span> attribute.

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: No animation to gate.
ARIA in the source: role="link"
role="presentation"
aria-current
aria-disabled
aria-hidden
aria-label

Examples

4 more states from the same story file.

defaultprimitives-breadcrumb--default ↗

keyboard flowprimitives-breadcrumb--keyboard-flow ↗

loadingprimitives-breadcrumb--loading ↗

below min viewportprimitives-breadcrumb--below-min-viewport ↗

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

Rule	Concept	Where
R4	Extends native els	Every part extends `React.ComponentProps<'…'>`
R6	data-slot on every part	data-slot="breadcrumb" / "-list" / "-item" / …
R7	className merged + ...rest	`cn(BASE, className)` + `{...props}` on every part
R10	Composition seam	BreadcrumbLink accepts `asChild` (server-safe slot)
R13	Ecosystem first	Lucide icons (ChevronRight / MoreHorizontal)
R18	Tailwind only	Zero inline style
R19	Tokens only	gap-xs / text-ui-sm / text-muted-foreground / size-4
R20	AA contrast	foreground vs muted-foreground; AA-cleared tokens
R25	Server component	No hooks → no 'use client'
R26	A11y from native els	`nav` + ordered list + `aria-current` + role

Minimum viewport

This primitive declares MIN_VIEWPORT = 480 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.

Opt-in to the dev-mode warning

<body data-interlace-dev>...</body>

Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: ChevronRight
MoreHorizontal
NPM dependencies: lucide-react
Registry dependencies: @interlace/theme
@interlace/cn

Source

The full implementation — components/ui/breadcrumb.tsx once installed.

252 lines · TypeScript

github ↗

import * as React from 'react';

// @interlace/breadcrumb v1.1.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/breadcrumb
// What changed since: https://ds.interlace.tools/c/breadcrumb#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Breadcrumb
 *
 * A server-rendered, semantically-tagged trail of ancestor links. The
 * compositional API mirrors the shadcn surface so consumers swap drop-in, and
 * `BreadcrumbLink` keeps a server-safe `asChild` seam (`React.cloneElement`,
 * NOT Base UI `useRender`) so the whole tree stays an RSC and composes with
 * `next/link` without forcing a client boundary.
 *
 * Anatomy:
 *   Breadcrumb (nav[aria-label="breadcrumb"], data-min-viewport)
 *     └─ BreadcrumbList (ol)
 *         ├─ BreadcrumbItem (li)

…232 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/breadcrumb.json