Breadcrumbs

Description

Breadcrumb is a compound navigation component that surfaces the path from a root context down to the current page. The root renders a <nav> landmark with aria-label="Breadcrumb", each segment is a BreadcrumbItem (rendered as <a> by default, or polymorphic via asChild), and BreadcrumbSeparator interleaves between items as a decorative divider. BreadcrumbEllipsis collapses any middle section that would make the trail too long.

Reach for it on screens that live several levels deep in a hierarchy: a file inside a folder inside a workspace, a setting inside a section inside an account, a record inside a project inside a team. It gives the user both a sense of place and a one-click way back up the tree. The visual weight stays low so it complements the page chrome instead of competing with the primary nav.

Don't use Breadcrumb for linear, ordered progress through a flow; use Stepper instead. Don't use it for paginating through a list; use Pagination. Don't use it as the app's top-level navigation between sibling views; that role belongs to Tabs or a primary nav rail. If you only need a single "back to parent" affordance, a Button with a leading chevron is lighter than a full trail.

Installation

pnpm dlx @create-ui/cli add breadcrumb

Anatomy

<Breadcrumb>
  <BreadcrumbItem />
  <BreadcrumbSeparator />
  <BreadcrumbItem />
  <BreadcrumbSeparator />
  <BreadcrumbEllipsis />
  <BreadcrumbSeparator />
  <BreadcrumbItem current />
</Breadcrumb>

Separators are not auto-injected; the consumer interleaves them between items. BreadcrumbEllipsis is optional and only used when a deep path is collapsed. The final segment is typically the current page, marked with the current prop so it stops behaving like a link.

Usage

import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"

<Breadcrumb>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbSeparator />
  <BreadcrumbItem href="/settings" current>
    Settings
  </BreadcrumbItem>
</Breadcrumb>

Examples

Variants

variant sets the hover and active-segment color on items. primary (default) tints hovered links with the brand color; neutral keeps everything tonal. The current segment always uses --color-strongest regardless of variant.

Appearance

appearance controls each item's surface treatment. ghost (default) is textual with no chrome and is the right pick for inline page trails. outline gives every segment a bordered chip, while solid swaps the border for a soft tinted fill; both read more like a toolbar.

Sizes

Three sizes (xs, sm, md) drive type, item height, icon size, and separator scale together. Pass the matching size to both BreadcrumbItem and BreadcrumbSeparator so the trail stays optically aligned.

Separators

BreadcrumbSeparator exposes three styles via variant. Reach for chevron (default) to convey directionality, slash for URL-like paths, and dot for compact rows where the divider should disappear into the layout.

With Icon

leadingIcon and trailingIcon slot glyphs on either side of the label. A leading icon is useful for the root segment (a folder, a workspace mark); a trailing icon is the convention for segments that open a dropdown.

Overflow with Ellipsis

BreadcrumbEllipsis collapses the middle of a long trail into a single … placeholder. It mirrors the item's variant, appearance, size, and shape so it visually belongs with the surrounding segments. Wire it to a menu with asChild upstream if you want the hidden segments to be discoverable.

Current Page

current marks the active segment, typically the last item. The component sets aria-current="page", swaps the text to --color-strongest, and disables pointer events so the segment stops behaving like a link.

Composition

Items accept arbitrary children, so you can mix labels with avatars, badges, or other primitives mid-path. Useful for team or version pickers embedded directly in the trail.

Accessibility

Breadcrumb is a custom composition, not a Radix primitive. The root renders as a <nav> landmark with aria-label="Breadcrumb", so assistive tech announces the trail as a named region. Items are real <a> tags, so native browser navigation and focus handling apply.

ARIA notes:

• The root sets aria-label="Breadcrumb" automatically; only override when localizing.
• current on BreadcrumbItem sets aria-current="page" and renders the segment non-interactive (pointer-events: none).
• disabled sets aria-disabled="true" and also data-disabled for styling hooks.
• BreadcrumbSeparator is role="presentation" + aria-hidden="true" so screen readers skip it as decorative.
• BreadcrumbEllipsis is decorative by default. If you wire it to a menu, swap its render via asChild upstream to a real <button> and supply an aria-label (e.g. "Show hidden path segments").

Styling

Tailwind override: pass className to merge Tailwind classes with the component's CVA classes (via cn()):

<BreadcrumbItem className="tracking-wide uppercase">Beta</BreadcrumbItem>

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="breadcrumb" on the root <nav>.
• data-slot="breadcrumb-item" on each item.
• data-slot="breadcrumb-item-icon" on the leading icon wrapper.
• data-slot="breadcrumb-item-content" on the inner text wrapper.
• data-slot="breadcrumb-item-caret" on the trailing icon wrapper.
• data-slot="breadcrumb-separator" on each separator.
• data-slot="breadcrumb-ellipsis" on the ellipsis.
• data-variant="<variant>", data-appearance="<appearance>", data-size="<size>" on items and the ellipsis.
• data-disabled, data-current on items and the ellipsis when those states are active.

Target a specific state in CSS:

[data-slot="breadcrumb-item"][data-current] {
  /* … */
}

Related Components

• Tabs: switch between sibling views inside a single screen; not a depth trail.
• Pagination: navigate between pages of a paged list.
• Stepper: sequential, ordered progress through a flow (checkout, onboarding).
• Button: single back or parent navigation when there is no depth to surface.

API Reference

Breadcrumb

Root <nav> landmark for the trail. Extends React.ComponentProps<"nav"> and sets aria-label="Breadcrumb" automatically. Sub-parts are not auto-injected; interleave BreadcrumbSeparator between BreadcrumbItems yourself.

Props

BreadcrumbItem

A single segment of the trail. Renders as <a> by default and extends React.ComponentProps<"a">, so any native anchor attribute (href, target, rel, onClick, …) is accepted. Use asChild to swap in a framework <Link> from Next.js, React Router, etc.

Props

Variants

BreadcrumbSeparator

Decorative divider between items. Renders a <span> with role="presentation" and aria-hidden="true" so it is skipped by assistive tech. Extends React.ComponentProps<"span">.

Props

Variants

BreadcrumbEllipsis

Compact placeholder for a collapsed middle section of a long path. Renders as a <span> containing ... and extends React.ComponentProps<"span">. Mirrors BreadcrumbItem's style axes so it visually belongs with the surrounding segments.

Props

Variants