Unified UI

Breadcrumb

A navigation trail component with separator, ellipsis truncation, and composable items for wayfinding.

Basic

A navigation trail component for wayfinding. Supports custom separators, ellipsis truncation for deep hierarchies, and both composable and declarative APIs.

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add breadcrumb
pnpm dlx @work-rjkashyap/unified-ui add breadcrumb
npx @work-rjkashyap/unified-ui add breadcrumb
bunx @work-rjkashyap/unified-ui add breadcrumb

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui
pnpm add @work-rjkashyap/unified-ui
yarn add @work-rjkashyap/unified-ui
bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Breadcrumb,
	BreadcrumbList,
	BreadcrumbItem,
	BreadcrumbLink,
	BreadcrumbPage,
	BreadcrumbSeparator,
	BreadcrumbEllipsis,
	BreadcrumbNav,
} from "@work-rjkashyap/unified-ui";

Composable API

The Breadcrumb uses a fully composable slot-based pattern. You build the trail from individual sub-components, giving you complete control over each segment.

Basic Trail

<Breadcrumb>
	<BreadcrumbList>
		<BreadcrumbItem>
			<BreadcrumbLink href="/">Home</BreadcrumbLink>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<BreadcrumbLink href="/products">Products</BreadcrumbLink>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<BreadcrumbPage>Widget Pro</BreadcrumbPage>
		</BreadcrumbItem>
	</BreadcrumbList>
</Breadcrumb>
  • BreadcrumbLink — A clickable breadcrumb segment that navigates to a URL.
  • BreadcrumbPage — The current page (non-clickable, rendered with aria-current="page").
  • BreadcrumbSeparator — A visual divider between segments (renders a chevron by default).

Declarative API

For simpler use cases, the BreadcrumbNav component accepts an array of items and renders the full trail automatically.

<BreadcrumbNav
	items={[
		{ label: "Home", href: "/" },
		{ label: "Products", href: "/products" },
		{ label: "Widget Pro" },
	]}
/>

The last item (without an href) is automatically treated as the current page.

With Ellipsis

For deep navigation hierarchies, use BreadcrumbEllipsis to collapse intermediate segments. This prevents the breadcrumb trail from becoming too long on narrow viewports.

The BreadcrumbEllipsis renders as "…" and can optionally be wrapped in a DropdownMenu or Popover to reveal the hidden segments on click.

Custom Separator

The BreadcrumbSeparator renders a chevron icon by default, but you can pass custom children to use any separator character or icon.

{
	/* Default chevron */
}
<BreadcrumbSeparator />;

{
	/* Slash separator */
}
<BreadcrumbSeparator>/</BreadcrumbSeparator>;

{
	/* Dot separator */
}
<BreadcrumbSeparator>·</BreadcrumbSeparator>;

{
	/* Custom icon */
}
import { ArrowRight } from "lucide-react";

<BreadcrumbSeparator>
	<ArrowRight className="size-3" />
</BreadcrumbSeparator>;

With Custom Separator Example

Use the asChild pattern (or the as prop) on BreadcrumbLink to render framework-specific link components like Next.js <Link>.

import Link from "next/link";

<Breadcrumb>
	<BreadcrumbList>
		<BreadcrumbItem>
			<BreadcrumbLink asChild>
				<Link href="/">Home</Link>
			</BreadcrumbLink>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<BreadcrumbLink asChild>
				<Link href="/products">Products</Link>
			</BreadcrumbLink>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<BreadcrumbPage>Widget Pro</BreadcrumbPage>
		</BreadcrumbItem>
	</BreadcrumbList>
</Breadcrumb>;

With Dropdown for Collapsed Items

Combine BreadcrumbEllipsis with a DropdownMenu to let users access collapsed breadcrumb segments.

<Breadcrumb>
	<BreadcrumbList>
		<BreadcrumbItem>
			<BreadcrumbLink href="/">Home</BreadcrumbLink>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<DropdownMenu>
				<DropdownMenuTrigger asChild>
					<BreadcrumbEllipsis />
				</DropdownMenuTrigger>
				<DropdownMenuContent>
					<DropdownMenuItem>
						<a href="/docs">Documentation</a>
					</DropdownMenuItem>
					<DropdownMenuItem>
						<a href="/docs/design-system">Design System</a>
					</DropdownMenuItem>
					<DropdownMenuItem>
						<a href="/components">Components</a>
					</DropdownMenuItem>
				</DropdownMenuContent>
			</DropdownMenu>
		</BreadcrumbItem>
		<BreadcrumbSeparator />
		<BreadcrumbItem>
			<BreadcrumbPage>Breadcrumb</BreadcrumbPage>
		</BreadcrumbItem>
	</BreadcrumbList>
</Breadcrumb>

Props

PropTypeDefaultDescription
classNamestring—Additional CSS classes on the <nav> element.
childrenReactNode—Should contain a single BreadcrumbList.
PropTypeDefaultDescription
classNamestring—Additional CSS classes on the <ol> element.
PropTypeDefaultDescription
classNamestring—Additional CSS classes on the <li> element.
PropTypeDefaultDescription
hrefstring—URL to navigate to.
asChildbooleanfalseMerge props onto the child element (for framework links).
classNamestring—Additional CSS classes.
PropTypeDefaultDescription
classNamestring—Additional CSS classes.
PropTypeDefaultDescription
childrenReactNodeChevron iconCustom separator content.
classNamestring—Additional CSS classes.
PropTypeDefaultDescription
classNamestring—Additional CSS classes.
PropTypeDefaultDescription
itemsBreadcrumbNavItem[]requiredArray of { label: string; href?: string } items.
separatorReactNodeChevron iconCustom separator to use between items.
classNamestring—Additional CSS classes.

Accessibility

Breadcrumbs follow the WAI-ARIA Breadcrumb pattern for full screen reader support.

  • The root Breadcrumb renders as a <nav> element with aria-label="Breadcrumb".
  • The trail is an ordered list (<ol>) for proper semantic structure.
  • The current page segment uses aria-current="page" (via BreadcrumbPage).
  • Separators are decorative and marked with aria-hidden="true" — they are not announced by screen readers.
  • The ellipsis element has an accessible label (aria-label="More breadcrumbs") so assistive technology users know collapsed items exist.
  • All links are keyboard focusable and show a visible focus ring via focus-visible.
  • Breadcrumb links use standard <a> semantics (or delegated to the child via asChild) for native browser behavior.

Design Tokens

TokenUsage
--foregroundCurrent page text color
--muted-foregroundLink text and separator color
--primaryLink hover text color
--duration-fastHover transition speed

Accordion

A collapsible accordion component with single and multiple expand modes, built on Radix UI.

Pagination

A page navigation component with smart ellipsis truncation, previous/next buttons, and a compact variant.

On this page

BasicInstallationOr install the full packageAnatomyComposable APIBasic TrailDeclarative APIWith EllipsisCustom SeparatorWith Custom Separator ExampleWith Framework LinksWith Dropdown for Collapsed ItemsPropsBreadcrumbBreadcrumbListBreadcrumbItemBreadcrumbLinkBreadcrumbPageBreadcrumbSeparatorBreadcrumbEllipsisBreadcrumbNav (Declarative)AccessibilityDesign Tokens