breadcrumb

Displays the path to the current resource using a hierarchy of links.

Installation

npx @gentleduck/cli add breadcrumb
npx @gentleduck/cli add breadcrumb

Usage

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Examples

Custom separator

Use a custom component as children for <BreadcrumbSeparator /> to create a custom separator.

import { SlashIcon } from "lucide-react"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>
      <SlashIcon />
    </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
import { SlashIcon } from "lucide-react"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>
      <SlashIcon />
    </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Dropdown

You can compose <BreadcrumbItem /> with a <DropdownMenu /> to create a dropdown in the breadcrumb.

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
 
...
 
<BreadcrumbItem>
  <DropdownMenu>
    <DropdownMenuTrigger>
      Components
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem>Documentation</DropdownMenuItem>
      <DropdownMenuItem>Themes</DropdownMenuItem>
      <DropdownMenuItem>GitHub</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</BreadcrumbItem>
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
 
...
 
<BreadcrumbItem>
  <DropdownMenu>
    <DropdownMenuTrigger>
      Components
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem>Documentation</DropdownMenuItem>
      <DropdownMenuItem>Themes</DropdownMenuItem>
      <DropdownMenuItem>GitHub</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</BreadcrumbItem>

Collapsed

We provide a <BreadcrumbEllipsis /> component to show a collapsed state when the breadcrumb is too long.

import { BreadcrumbEllipsis } from "@/components/ui/breadcrumb"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    {/* ... */}
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    {/* ... */}
  </BreadcrumbList>
</Breadcrumb>
import { BreadcrumbEllipsis } from "@/components/ui/breadcrumb"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    {/* ... */}
    <BreadcrumbItem>
      <BreadcrumbEllipsis />
    </BreadcrumbItem>
    {/* ... */}
  </BreadcrumbList>
</Breadcrumb>

Link component

To use a custom link component from your routing library, you can use the asChild prop on <BreadcrumbLink />.

import { Link } from "next/link"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink asChild>
        <Link href="/">Home</Link>
      </BreadcrumbLink>
    </BreadcrumbItem>
    {/* ... */}
  </BreadcrumbList>
</Breadcrumb>
import { Link } from "next/link"
 
...
 
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink asChild>
        <Link href="/">Home</Link>
      </BreadcrumbLink>
    </BreadcrumbItem>
    {/* ... */}
  </BreadcrumbList>
</Breadcrumb>

Responsive

Here's an example of a responsive breadcrumb that composes <BreadcrumbItem /> with <BreadcrumbEllipsis />, <DropdownMenu />, and <Drawer />.

It displays a dropdown on desktop and a drawer on mobile.

API Reference

Breadcrumb

  • separator (React.ReactNode, optional): Custom separator element between breadcrumb items. Defaults to ChevronRight.
  • ...props (React.ComponentPropsWithRef<'nav'>): Native nav element props.

Behavior:

  • Renders a <nav> with aria-label="breadcrumb" for accessibility.
  • Serves as the root wrapper for the breadcrumb navigation structure.

BreadcrumbList

  • props (React.ComponentPropsWithRef<'ol'>): Native ol element props.

Behavior:

  • Displays breadcrumb items in a flex row with spacing and wrapping support.

BreadcrumbItem

  • props (React.ComponentPropsWithRef<'li'>): Native li element props.

Behavior:

  • Represents a single breadcrumb step.

BreadcrumbLink

  • asChild (boolean, optional): If true, uses the Slot component instead of rendering an <a> directly.
  • ...props (React.ComponentPropsWithRef<'a'>): Native a element props.

Behavior:

  • Renders a link for a breadcrumb step with hover styles.

BreadcrumbPage

  • props (React.ComponentPropsWithRef<'span'>): Native span element props.

Behavior:

  • Marks the current page in the breadcrumb trail.
  • Uses aria-current="page" and aria-disabled="true".

BreadcrumbSeparator

  • props (React.ComponentProps<'li'>): Native li element props.

Behavior:

  • Visually separates breadcrumb items.
  • Uses role="presentation" and aria-hidden="true".

BreadcrumbEllipsis

  • props (React.ComponentProps<'span'>): Native span element props.

Behavior:

  • Displays an ellipsis icon (<MoreHorizontal />) to indicate collapsed breadcrumb items.
  • Includes a visually hidden "More" label for screen readers.
BadgeButton