Breadcrumb
A navigation trail with separators, collapsible ellipsis, and a standalone back link for page headers.
Installation
$
npx shadcn@latest add https://ui.mattdowney.com/r/breadcrumb.jsonUsage
import {
Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink,
BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis, BreadcrumbBack,
} from "@/components/ui/breadcrumb"Examples
Default
The full trail, one BreadcrumbItem per level. The last crumb is a BreadcrumbPage, not a link: it is the page you are already on.
Back Link
A standalone “up one level” affordance for page headers. Use size="lg" at header scale.
Collapsed
Collapse the middle of a long trail behind an ellipsis.
Collapsed with Dropdown
Wrap the ellipsis in a dropdown to reveal the hidden crumbs.
Long current page
A long record name as the last crumb stops at 20rem with an ellipsis, and the full name stays in title. Change the cap with a max-w-* on BreadcrumbPage.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| renderBreadcrumbLink, BreadcrumbBack | React.ReactElement | None | Replaces the default <a> with your own element, e.g. render={<Link href="/" />}. Base UI merges props onto it. |
| sizeBreadcrumbBack | "default" | "lg" | "default" | default is inline/toolbar scale (14px); lg sits at page-header scale (20px). The chevron scales with it. |
| classNameBreadcrumbPage | string | None | The current crumb, and every link crumb, truncates at max-w-crumb (24 characters, --container-crumb) with an ellipsis, and a plain-text name is repeated in title so the full name stays reachable. Pass another max-w-* to change the cap. |
| childrenBreadcrumbSeparator | React.ReactNode | None | Overrides the default chevron separator, e.g. pass a / for a slash-style trail. |
renderBreadcrumbLink, BreadcrumbBackReact.ReactElementReplaces the default <a> with your own element, e.g. render={<Link href="/" />}. Base UI merges props onto it. |
sizeBreadcrumbBack"default" | "lg" = "default"default is inline/toolbar scale (14px); lg sits at page-header scale (20px). The chevron scales with it. |
classNameBreadcrumbPagestringThe current crumb, and every link crumb, truncates at max-w-crumb (24 characters, --container-crumb) with an ellipsis, and a plain-text name is repeated in title so the full name stays reachable. Pass another max-w-* to change the cap. |
childrenBreadcrumbSeparatorReact.ReactNodeOverrides the default chevron separator, e.g. pass a / for a slash-style trail. |
"use client"
import * as React from "react"
import { IconChevronLeft as ChevronLeft, IconChevronRight as ChevronRight, IconDots as MoreHorizontal } from "@tabler/icons-react"
import { useRender } from "@base-ui/react/use-render"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/registry/lib/utils"
/* ─────────────────────────────────────────────────────────
* BREADCRUMB
*
* A navigation trail. Not a Base UI primitive; pure semantic
* DOM (nav > ol > li). Links are polymorphic via Base UI's
* `render` prop (never `asChild`): pass `render={<Link />}` to
* swap in a router link.
* ───────────────────────────────────────────────────────── */
// @use-when the path back up through a page hierarchy.
function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
return (
<nav
data-slot="breadcrumb"
aria-label="breadcrumb"
className={className}
{...props}
/>
)
}
function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
return (
// One line, never wrapped. Each separator is its own list item, so a
// wrapping trail could leave a chevron hanging at the end of a line with
// its crumb on the next. Instead the crumbs shrink and cut off with an
// ellipsis (each keeps its full name in `title`), and the chevrons hold
// their size.
<ol
data-slot="breadcrumb-list"
className={cn(
"flex min-w-0 flex-nowrap items-center gap-1.5 text-sm text-muted-foreground",
className
)}
{...props}
/>
)
}
function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
return (
<li
data-slot="breadcrumb-item"
className={cn("inline-flex min-w-0 max-w-full items-center gap-1.5", className)}
{...props}
/>
)
}
// Polymorphic link. Renders an <a> by default; pass `render={<Link />}`
// (or any element) to compose with a router. Never uses `asChild`.
// A long name is cut at `max-w-crumb` (24 characters, a token) with an
// ellipsis, like BreadcrumbPage, and a plain-text name is repeated in `title`.
function BreadcrumbLink({
className,
render,
children,
...props
}: useRender.ComponentProps<"a">) {
return useRender({
render: render ?? <a />,
props: {
"data-slot": "breadcrumb-link",
title: typeof children === "string" ? children : undefined,
children,
className: cn(
"min-w-0 max-w-crumb truncate",
// Modest padding with a matching negative margin: the hit area and the
// focus ring get room around the words and the trail does not move.
"-mx-1 -my-0.5 rounded-sm px-1 py-0.5 outline-none transition-colors duration-small ease-small hover:text-foreground focus-visible:text-foreground focus-visible:ring-ring-focus focus-visible:ring-[3px]",
className
),
...props,
},
})
}
// The current page, the last crumb. Non-interactive on purpose. A long record
// name (a post title) is cut at `max-w-crumb` (24 characters, so the cap
// follows the type size, not a pixel width) with an ellipsis, and a plain-text
// name is repeated in `title` so the full name stays reachable. Retune
// `--container-crumb` in `:root`, or pass your own `max-w-*` through className.
function BreadcrumbPage({ className, children, ...props }: React.ComponentProps<"span">) {
return (
<span
data-slot="breadcrumb-page"
aria-current="page"
title={typeof children === "string" ? children : undefined}
className={cn("min-w-0 max-w-crumb truncate font-normal text-foreground", className)}
{...props}
>
{children}
</span>
)
}
// Separator between crumbs. Defaults to a chevron; pass children (e.g. a
// slash) to override. Decorative, so hidden from assistive tech.
function BreadcrumbSeparator({
children,
className,
...props
}: React.ComponentProps<"li">) {
return (
<li
data-slot="breadcrumb-separator"
role="presentation"
aria-hidden="true"
className={cn("shrink-0 [&>svg]:size-3.5", className)}
{...props}
>
{children ?? <ChevronRight />}
</li>
)
}
// Collapsed marker for long trails. Decorative on its own; wrap it in a
// DropdownMenuTrigger to reveal the hidden crumbs.
function BreadcrumbEllipsis({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
data-slot="breadcrumb-ellipsis"
role="presentation"
aria-hidden="true"
className={cn(
"flex size-8 pointer-coarse:size-11 items-center justify-center [&>svg]:size-4",
className
)}
{...props}
>
<MoreHorizontal />
<span className="sr-only">More</span>
</span>
)
}
/* ─────────────────────────────────────────────────────────
* BACK LINK
*
* A standalone "up one level" affordance for page headers:
* a leading chevron-left + the parent's name. Sized `default`
* for inline/toolbar use, `lg` to sit at header scale. The
* chevron nudges left on hover to signal "go back".
* ───────────────────────────────────────────────────────── */
const backVariants = cva(
// hover:[&>svg] not group-hover: the chevron is a CHILD of this link, so its
// hover state IS this element's hover. `group-hover` reads a hovered ANCESTOR
// marked `group`, and an element is not its own ancestor, so it never fired.
"inline-flex w-fit items-center rounded-sm font-medium text-foreground outline-none transition-colors duration-small ease-small focus-visible:ring-ring-focus focus-visible:ring-[3px] [&>svg]:shrink-0 [&>svg]:text-muted-foreground [&>svg]:transition-[color,transform] [&>svg]:duration-small [&>svg]:ease-small hover:[&>svg]:text-foreground motion-safe:hover:[&>svg]:-translate-x-0.5",
{
variants: {
size: {
default: "gap-1.5 text-sm [&>svg]:size-4",
lg: "gap-2 text-xl [&>svg]:size-5",
},
},
defaultVariants: {
size: "default",
},
}
)
function BreadcrumbBack({
className,
size,
children,
render,
...props
}: useRender.ComponentProps<"a"> & VariantProps<typeof backVariants>) {
return useRender({
render: render ?? <a />,
props: {
"data-slot": "breadcrumb-back",
className: cn(backVariants({ size }), className),
children: (
<>
<ChevronLeft />
{children}
</>
),
...props,
},
})
}
export {
Breadcrumb,
BreadcrumbList,
BreadcrumbItem,
BreadcrumbLink,
BreadcrumbPage,
BreadcrumbSeparator,
BreadcrumbEllipsis,
BreadcrumbBack,
}