Breadcrumbs

Breadcrumbs show where the current page sits in a site's hierarchy and let users jump back to any ancestor. Use them on deep, nested routes such as docs sections, dashboards, or file paths.

Preview

Installation

npx shadcn@latest add @cubby-ui/breadcrumbs

Usage

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

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink />
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage />
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Composition

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

Examples

Variants

Use variant on Breadcrumb to switch between the plain default and a framed surface style.

Size Variants

Use size on Breadcrumb to scale the text and spacing.

Custom Separator

Pass children to BreadcrumbSeparator to replace the default chevron.

Custom Separator with Prop

Use the separator prop on BreadcrumbSeparator to set the divider element.

With Icons

Place an icon inside BreadcrumbLink to add context to an item.

With Ellipsis

Use BreadcrumbEllipsis to collapse the middle of a long path.

Dropdown

Compose a BreadcrumbItem with a DropdownMenu to collapse part of the path into a menu.

With Next.js Link

Use the render prop on BreadcrumbLink to render a Next.js Link.

With Accessibility Features

Add aria-label to items and the nav to clarify the trail for assistive tech.

Accessibility

The Breadcrumb nav defaults to aria-label="breadcrumb". BreadcrumbPage marks the current location with role="link", aria-disabled="true", and aria-current="page", so assistive tech announces it as the current, non-actionable page. BreadcrumbLink shows a visible focus ring on keyboard focus. Separators are hidden with aria-hidden, and BreadcrumbEllipsis carries a screen-reader label ("More pages" by default) for the collapsed items.

Labeling a collapsed trigger

When you collapse items into a DropdownMenu, give the icon-only trigger an accessible name. BreadcrumbEllipsis is hidden from assistive tech, so the button has no name on its own.

<DropdownMenuTrigger render={<Button variant="ghost" size="icon_sm" />}>
  <BreadcrumbEllipsis />
  <span className="sr-only">Toggle menu</span>
</DropdownMenuTrigger>

API Reference

Breadcrumbs are custom styled components built on native HTML elements (nav, ol, li, a, span). BreadcrumbLink is polymorphic through Base UI's render prop; the other parts pass through standard attributes for their element.

Props

Breadcrumb

Navigation landmark that wraps the trail. Renders a nav.

BreadcrumbLink

Interactive ancestor link. Renders an a by default.

BreadcrumbSeparator

Divider between items. Renders an li marked aria-hidden, defaulting to a chevron icon.

BreadcrumbEllipsis

Collapsed indicator for the middle of a long path. Renders a span marked aria-hidden with a screen-reader label.