Breadcrumb

A composable, surface-less navigation primitive for showing the hierarchical path back to the top of a screen — Dashboard → Settings → current page.

Examples

Two-level path

Deep path with collapsed middle

Props

Breadcrumb

Prop	Type	Default	Description
aria-label	string	"breadcrumb"	Accessible label for the <nav> wrapper. Override when the breadcrumb sits inside a region that already has a label.
className	string	-	Additional CSS classes applied to the root <nav>.

BreadcrumbLink

Prop	Type	Default	Description
href	string	-	When set, renders as an <a>. When unset, renders as a <button> for in-app click handlers. asChild wraps a custom element instead.
asChild	boolean	false	Render the link as the child element via Slot — pair with Next.js Link or any custom router link.

Accessibility

Root renders a <nav aria-label="breadcrumb">
BreadcrumbList renders an ordered <ol> so the path order is meaningful to assistive tech
BreadcrumbPage marks the current page with aria-current="page" and is not interactive
BreadcrumbSeparator is decorative — hidden from the accessibility tree

Sidecar

The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/breadcrumb.md and shipped inside the published @gradeui/ui tarball.

---
name: Breadcrumb
import: "@gradeui/ui"
subcomponents: [BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis]
props:
  - Breadcrumb: aria-label? (defaults to "breadcrumb") — passed to the underlying <nav>
  - BreadcrumbList: className? — the <ol> wrapper; usually no overrides needed
  - BreadcrumbItem: className? — wraps a single crumb (link or page)
  - BreadcrumbLink: href? — renders as <a> when set, <button> when not; asChild? wraps a custom element
  - BreadcrumbPage: className? — the current page; rendered as a non-interactive <span> with aria-current="page"
  - BreadcrumbSeparator: children? (defaults to a chevron) — the visual separator between crumbs
  - BreadcrumbEllipsis: className? — collapsed middle crumbs marker, use between BreadcrumbItems
when_to_use: Reach for Breadcrumb whenever a screen sits inside a hierarchy and you want the path back to the top to be visible. Common spots: above page titles in admin/CMS screens, top of Settings detail pages, after a router redirect when the URL implies depth. Use the current page as a <BreadcrumbPage> (non-clickable) and prior levels as <BreadcrumbLink>. For a horizontal "top nav" of peer destinations use Side Menu or Tabs instead — Breadcrumb is strictly for hierarchical path.
composes_with: [AppShellMain, Card (in CardHeader), Dialog]
aliases: [breadcrumb, breadcrumbs, crumbs, path, page hierarchy, path bar, navigation trail, finder path]
---

```jsx
// Two-level path — Dashboard → current page.
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Dashboard</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Settings</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

```jsx
// Deep path with collapsed middle — useful when the path is long.
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/projects/acme">Acme</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Billing</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```