Breadcrumb

InstallCopy Anchor Link

pnpm exec vegastack-design verify breadcrumb

pnpm dlx shadcn@4.21.0 add @vegastack/breadcrumb

UsageCopy Anchor Link

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

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink render={<a href="/" />}>Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink render={<a href="/components" />}>
        Components
      </BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>;

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

CompositionCopy Anchor Link

Breadcrumb is a nav labelled breadcrumb; BreadcrumbList is the ol inside it. Every segment is a BreadcrumbItem, separators sit between items as their own li, and the last segment is a BreadcrumbPage rather than a link.

Breadcrumb
└── BreadcrumbList
    ├── BreadcrumbItem
    │   └── BreadcrumbLink
    ├── BreadcrumbSeparator
    ├── BreadcrumbItem
    │   └── BreadcrumbLink
    ├── BreadcrumbSeparator
    └── BreadcrumbItem
        └── BreadcrumbPage

BasicCopy Anchor Link

A home link, a section link and the current page. BreadcrumbLink renders an a by default, so href goes straight on it.

Custom separatorCopy Anchor Link

Pass children to BreadcrumbSeparator to replace the default chevron. The separator is role="presentation" and aria-hidden, so whatever it renders is decoration and never enters the accessible name of the trail.

DropdownCopy Anchor Link

Compose BreadcrumbItem with a DropdownMenu when a segment has siblings the reader can switch to. The trigger is a real button, so it is reachable by keyboard and announces its expanded state.

CollapsedCopy Anchor Link

BreadcrumbEllipsis stands in for the segments a long trail hides. It is role="presentation" and aria-hidden — decoration, not a control — so when the hidden segments must stay reachable, wrap it in a real trigger, as the example at the top of this page does with a Button size="icon-sm" and a DropdownMenu.

Link componentCopy Anchor Link

render on BreadcrumbLink replaces the element it renders, which is how a routing library's link gets the breadcrumb's styling and its data-slot. In a Next.js app that is render={<Link href="/docs" />}; this page has no router, so the render target below is a plain anchor.

RTLCopy Anchor Link

Wrap the subtree in DirectionProvider direction="rtl" so Base UI resolves logical sides, and set dir on the elements that portal out of it. The default separator carries rtl:rotate-180, so the chevron points the way the text reads; a dropdown inside the trail aligns to end instead of start.

API ReferenceCopy Anchor Link

BreadcrumbCopy Anchor Link

BreadcrumbListCopy Anchor Link

BreadcrumbItemCopy Anchor Link

BreadcrumbLinkCopy Anchor Link

BreadcrumbPageCopy Anchor Link

BreadcrumbSeparatorCopy Anchor Link

BreadcrumbEllipsisCopy Anchor Link

AccessibilityCopy Anchor Link

• Breadcrumb is a nav with aria-label="breadcrumb" wrapping an ordered list, which is the APG breadcrumb pattern: assistive technology reads the trail as a landmark and the segments in order.
• BreadcrumbPage is the current page. It carries aria-current="page" and aria-disabled, so it is announced as the destination the reader is already on rather than as a link they can follow.
• BreadcrumbSeparator and BreadcrumbEllipsis are both role="presentation" and aria-hidden — neither is a control and neither adds words to the trail. A collapsed trail that must stay navigable puts the ellipsis inside a real trigger with its own accessible name.
• Focus is the global 2px :focus-visible outline from base.css; nothing in the trail paints a ring glow.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/breadcrumb.patch. Every hunk:

• A11Y-2 — BreadcrumbLink gains relative after:absolute after:inset-x-0 after:-inset-y-1 after:content-['']. Its visible box is one line of 14px text, measured 20px tall by the geometry lane — 4px under the floor — and a breadcrumb is a row of navigation controls, not prose, so SC 2.5.8's inline-text exception does not reach it. The invisible area grows the target on the block axis only, so two adjacent crumbs cannot fight for a pixel; nothing moves and nothing paints. The ellipsis is untouched: it is role="presentation" aria-hidden, and upstream's own Collapsed example wraps it in a Button size="icon-sm" that is already 32px. breadcrumb.test.tsx asserts that shape, so a future upstream that makes the ellipsis itself the control fails here.
• API-16 — "use client" is added. Upstream ships none, but BreadcrumbLink calls useRender, which calls React.useRef internally; under the react-server condition that hook is undefined, so a Server Component rendering a breadcrumb link throws on import. The boundary belongs at the lowest interactive leaf, and this file is it.
• DOC-2 — import { cn } from "cn" becomes @vegastack/design; our npm layer owns cn.
• DOC-1 — prettier reflow plus the registry-stamp.mjs provenance header the three-copy model needs; no decision of its own.