Breadcrumb
Displays the path to the current resource using a hierarchy of links.
Shadcn UI
LucideInstallation
npx shadcn@latest add @redpanda/breadcrumbpnpm dlx shadcn@latest add @redpanda/breadcrumbyarn dlx shadcn@latest add @redpanda/breadcrumbbunx shadcn@latest add @redpanda/breadcrumbnubx shadcn@latest add @redpanda/breadcrumbaube dlx shadcn@latest add @redpanda/breadcrumbUsage
import { Breadcrumb, BreadcrumbHeader, 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>When to use
Use Breadcrumb to help users understand their current location within a site hierarchy and navigate back to parent levels:
Use Breadcrumb when:
- Site has 3 or more hierarchical levels
- Users need to understand their current location
- Content is organized in clear categories
- Users frequently navigate between levels
- Building e-commerce or documentation sites
Don’t use Breadcrumb when:
- Site has flat structure (1-2 levels)
- Navigation path is not hierarchical
- Current page is the home/landing page
- Users rarely need to backtrack
- Primary navigation is sufficient
Anatomy
The Breadcrumb component creates a horizontal navigation trail with clear hierarchy:
Breadcrumb Container┌─────────────────────────────────────────────────────────────┐│ BreadcrumbList (nav element) ││ ┌─────────────────────────────────────────────────────────┐ ││ │ BreadcrumbItem → BreadcrumbSeparator → BreadcrumbItem │ ││ │ ┌─────────────┐ ┌───────────────┐ ┌───────────────┐ │ ││ │ │BreadcrumbLink│ │ ChevronRight │ │BreadcrumbPage │ │ ││ │ │ (clickable) │ │ (separator) │ │ (current page)│ │ ││ │ └─────────────┘ └───────────────┘ └───────────────┘ │ ││ └─────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────┘
Advanced Patterns:- BreadcrumbEllipsis for collapsed long paths- DropdownMenu integration for category navigation- Responsive with Drawer on mobileComponent Hierarchy:
- Breadcrumb (Root): Main navigation wrapper with semantic meaning
- BreadcrumbHeader: Optional header wrapper for layout and spacing
- BreadcrumbList: Ordered list container for screen readers
- BreadcrumbItem: Individual breadcrumb step wrapper
- BreadcrumbLink: Clickable navigation link (for parent pages)
- BreadcrumbPage: Current page indicator (non-clickable)
- BreadcrumbSeparator: Visual divider between items
- BreadcrumbEllipsis: Collapsed state for long breadcrumbs
Key Features:
- Semantic HTML: Uses
<nav>and<ol>for accessibility - Keyboard Navigation: Full keyboard support for links
- Screen Reader Support: Proper ARIA labels and structure
- Customizable Separators: Icons or custom components
- Responsive: Collapsible with ellipsis and dropdowns
- Framework Integration: Works with Next.js Link and other routers
Examples
Custom separator
Use a custom component as children for <BreadcrumbSeparator /> to create a custom separator.
import { Slash } from "lucide-react"
...
<Breadcrumb> <BreadcrumbList> <BreadcrumbItem> <BreadcrumbLink href="/">Home</BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator> <Slash /> </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 className="flex items-center gap-1"> Components <ChevronDownIcon /> </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>Link component
Use the render prop on <BreadcrumbLink /> to supply a custom anchor or a routing library’s link component. Custom components must forward native anchor props and refs. The supplied element can own its children.
<Breadcrumb> <BreadcrumbList> <BreadcrumbItem> <BreadcrumbLink render={<a href="/">Home</a>} /> </BreadcrumbItem> {/* ... */} </BreadcrumbList></Breadcrumb>Card component
You can wrap the breadcrumbs in a Card component to make them stand out more.
<Card size="sm"> <CardContent> <Breadcrumb> <BreadcrumbList> <BreadcrumbItem> <BreadcrumbLink aria-label="Home" href="/"> <Home className="size-4" /> </BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator /> <BreadcrumbItem> <BreadcrumbLink href="/">Components</BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator /> <BreadcrumbItem> <BreadcrumbPage>Breadcrumb</BreadcrumbPage> </BreadcrumbItem> </BreadcrumbList> </Breadcrumb> </CardContent></Card>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. Labels remain readable in full and wrap onto another row when needed, rather than being capped and truncated. Desktop menu destinations use DropdownMenuLinkItem so keyboard selection follows the native link.
Header wrapper
Use the <BreadcrumbHeader /> component to wrap your breadcrumb in a header with consistent layout and spacing. This is particularly useful when integrating breadcrumbs into layouts with collapsible sidebars.
import { BreadcrumbHeader } from "@/components/ui/breadcrumb"
...
<BreadcrumbHeader> <Breadcrumb> <BreadcrumbList> <BreadcrumbItem> <BreadcrumbLink href="/">Home</BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator /> <BreadcrumbItem> <BreadcrumbLink href="/components">Components</BreadcrumbLink> </BreadcrumbItem> <BreadcrumbSeparator /> <BreadcrumbItem> <BreadcrumbPage>Breadcrumb</BreadcrumbPage> </BreadcrumbItem> </BreadcrumbList> </Breadcrumb></BreadcrumbHeader>The header wrapper provides:
- Fixed height (64px) with responsive behavior for collapsible sidebars (48px)
- Flexbox layout with consistent gap spacing
- Smooth width and height transitions
Leading icons
Compose an icon and text inside BreadcrumbLink or BreadcrumbPage. Both parts own their icon alignment and spacing; do not repeat flex or gap classes on them. Size the icon itself as needed.
<BreadcrumbLink href="/topics"> <Folder className="size-3.5" /> Topics</BreadcrumbLink>Loading state
Copy resource ID
Credits
- We take our inspiration from Shadcn UI for the breadcrumb style.