Breadcrumb

Breadcrumb shows the current resource within a hierarchy and links back to its parent levels.

Purpose

Breadcrumb shows the current resource within a hierarchy and provides short links back to its parent levels.

Page trail

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

export function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem><BreadcrumbPage>Button</BreadcrumbPage></BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/breadcrumb

Import

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

Need the machine-readable source metadata? View registry JSON.

Usage

Breadcrumb shows hierarchy for nested docs or app areas. The current page is text, not a link. Pass render to BreadcrumbLink to integrate framework links such as next/link.

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

export function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem><BreadcrumbPage>Button</BreadcrumbPage></BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

Examples

Plain trails, collapsed items, ellipsis menus and custom separators compose from the same slots.

Basic trail

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="#">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Collapsed item

BreadcrumbEllipsis stands in for hidden levels without its own menu.

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Ellipsis menu

The ellipsis becomes a MenuTrigger so hidden levels stay reachable.

<BreadcrumbItem>
  <Menu>
    <MenuTrigger
      render={
        <Button
          aria-label="Show hidden breadcrumb items"
          className="-m-1.5 text-muted-foreground"
          size="icon-sm"
          variant="ghost"
        />
      }
    >
      <BreadcrumbEllipsis />
    </MenuTrigger>
    <MenuPopup align="start">
      <MenuItem>Docs</MenuItem>
      <MenuItem>Particles</MenuItem>
    </MenuPopup>
  </Menu>
</BreadcrumbItem>

Custom separator

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator> / </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbLink href="#">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator> / </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Breadcrumb renders the named navigation landmark and BreadcrumbList contains its ordered items.
Use BreadcrumbLink for parent destinations and BreadcrumbPage for the current, non-interactive page.
BreadcrumbSeparator and BreadcrumbEllipsis are decorative.
Compose an ellipsis menu with the canonical Menu primitives when hidden levels need to remain reachable.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Breadcrumb itself has no mount or exit animation.
An ellipsis menu uses Menu motion; Breadcrumb adds no local motion values.

Accessibility

Keep the navigation landmark label and aria-current="page" semantics.
Every parent link needs a real destination.
Separators and ellipsis glyphs must not be announced as navigation targets.
An ellipsis menu must remain keyboard and focus accessible through Menu.

Implementation Guidance

Use Breadcrumb for hierarchy, not primary navigation, tabs, steps, filters, or process status.
Preserve native landmark, current-page, separator, ellipsis, and slot attributes.
Use existing Breadcrumb parts instead of wrapper primitives.