ui/components/breadcrumbs

Breadcrumbs

Compound breadcrumb navigation with auto-separator and composable parts for links, collapsed items, and custom separators.

Preview

tsx

1 import { Breadcrumbs } from "@/components/ui/breadcrumbs";2 3 export default function BreadcrumbsDefault() {4   return (5     <Breadcrumbs>6       <Breadcrumbs.Item>7         <Breadcrumbs.Link href="/ui/docs">Docs</Breadcrumbs.Link>8       </Breadcrumbs.Item>9       <Breadcrumbs.Item>10         <Breadcrumbs.Link href="/ui/docs/components">Components</Breadcrumbs.Link>11       </Breadcrumbs.Item>12       <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>13     </Breadcrumbs>14   );15 }16

Installation

$pnpm exec dgadd add ui/breadcrumbs

[Installs to]src/components/ui/breadcrumbs[Item]ui/breadcrumbs

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 import { Breadcrumbs } from "@/components/ui/breadcrumbs";2 3 export default function BreadcrumbsDefault() {4   return (5     <Breadcrumbs>6       <Breadcrumbs.Item>7         <Breadcrumbs.Link href="/ui/docs">Docs</Breadcrumbs.Link>8       </Breadcrumbs.Item>9       <Breadcrumbs.Item>10         <Breadcrumbs.Link href="/ui/docs/components">Components</Breadcrumbs.Link>11       </Breadcrumbs.Item>12       <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>13     </Breadcrumbs>14   );15 }16

Examples

Custom Separator

Preview

tsx

1 import { Breadcrumbs } from "@/components/ui/breadcrumbs";2 import { Chevron } from "@/components/ui/icons";3 4 export default function BreadcrumbsCustomSeparator() {5   return (6     <Breadcrumbs separator={<Chevron direction="right" size="sm" />}>7       <Breadcrumbs.Item>8         <Breadcrumbs.Link href="/ui/docs">Docs</Breadcrumbs.Link>9       </Breadcrumbs.Item>10       <Breadcrumbs.Item>11         <Breadcrumbs.Link href="/ui/docs/components">Components</Breadcrumbs.Link>12       </Breadcrumbs.Item>13       <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>14     </Breadcrumbs>15   );16 }17

Custom Link

Preview

tsx

1 "use client";2 3 import { Breadcrumbs } from "@/components/ui/breadcrumbs";4 5 // Simulated framework link component (replace with Next.js Link, React Router NavLink, etc.).6 function AppLink(7   props: React.AnchorHTMLAttributes<HTMLAnchorElement> & { ref?: React.Ref<HTMLAnchorElement> },8 ) {9   return <a {...props} />;10 }11 12 // This demo's own styling, passed through Breadcrumbs.Link's className, so the13 // render-prop path is visibly distinct from the plain-anchor default.14 const FRAMEWORK_LINK_CLASS = "underline decoration-dotted underline-offset-4 text-foreground/80";15 16 export default function BreadcrumbsCustomLink() {17   return (18     <div className="flex flex-col gap-2">19       <Breadcrumbs>20         <Breadcrumbs.Item>21           <Breadcrumbs.Link className={FRAMEWORK_LINK_CLASS}>22             {(props) => (23               <AppLink href="/ui/docs" {...props}>24                 Docs25               </AppLink>26             )}27           </Breadcrumbs.Link>28         </Breadcrumbs.Item>29         <Breadcrumbs.Item>30           <Breadcrumbs.Link className={FRAMEWORK_LINK_CLASS}>31             {(props) => (32               <AppLink href="/ui/docs/components" {...props}>33                 Components34               </AppLink>35             )}36           </Breadcrumbs.Link>37         </Breadcrumbs.Item>38         <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>39       </Breadcrumbs>40       <p className="text-2xs font-mono text-muted-foreground">41         The dotted links are rendered by the framework Link component; className, ref, and42         aria-current arrive through the render prop.43       </p>44     </div>45   );46 }47

Ellipsis

Preview

tsx

1 import { Breadcrumbs } from "@/components/ui/breadcrumbs";2 3 export default function BreadcrumbsEllipsis() {4   return (5     <Breadcrumbs>6       <Breadcrumbs.Item>7         <Breadcrumbs.Link href="/ui/docs">Docs</Breadcrumbs.Link>8       </Breadcrumbs.Item>9       <Breadcrumbs.Item>10         <Breadcrumbs.Ellipsis />11       </Breadcrumbs.Item>12       <Breadcrumbs.Item>Breadcrumbs</Breadcrumbs.Item>13     </Breadcrumbs>14   );15 }16

Constrained Width

Preview

tsx

1 import { Breadcrumbs } from "@/components/ui/breadcrumbs";2 3 // Breadcrumbs renders the trail it is given. In a constrained column, collapse4 // the middle levels into Breadcrumbs.Ellipsis and clip the long leaf crumb5 // instead of letting the trail wrap across three rows.6 export default function BreadcrumbsTruncated() {7   return (8     <div className="flex w-[280px] flex-col gap-4 border border-dashed border-foreground/20 p-3">9       <div className="flex flex-col gap-1.5">10         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">11           full trail12         </span>13         {/* Two trails in one demo: each nav landmark needs its own name. */}14         <Breadcrumbs aria-label="Full breadcrumb trail">15           <Breadcrumbs.Item>16             <Breadcrumbs.Link href="/ui">UI</Breadcrumbs.Link>17           </Breadcrumbs.Item>18           <Breadcrumbs.Item>19             <Breadcrumbs.Link href="/ui/docs">Docs</Breadcrumbs.Link>20           </Breadcrumbs.Item>21           <Breadcrumbs.Item>22             <Breadcrumbs.Link href="/ui/docs/components">Components</Breadcrumbs.Link>23           </Breadcrumbs.Item>24           <Breadcrumbs.Item>25             <Breadcrumbs.Link href="/ui/docs/components/navigation">Navigation</Breadcrumbs.Link>26           </Breadcrumbs.Item>27           <Breadcrumbs.Item>Breadcrumbs component</Breadcrumbs.Item>28         </Breadcrumbs>29       </div>30 31       <div className="flex flex-col gap-1.5">32         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">33           collapsed + clipped leaf34         </span>35         <Breadcrumbs aria-label="Collapsed breadcrumb trail">36           <Breadcrumbs.Item>37             <Breadcrumbs.Link href="/ui">UI</Breadcrumbs.Link>38           </Breadcrumbs.Item>39           <Breadcrumbs.Item>40             <Breadcrumbs.Ellipsis label="3 collapsed levels" />41           </Breadcrumbs.Item>42           <Breadcrumbs.Item>43             {/* title keeps the full text reachable on hover once it is clipped */}44             <span className="block max-w-[14ch] truncate" title="Breadcrumbs component">45               Breadcrumbs component46             </span>47           </Breadcrumbs.Item>48         </Breadcrumbs>49       </div>50     </div>51   );52 }53

API Reference

Breadcrumbs

Name	Type	Default	Description
separator	ReactNode	"/"	Separator rendered between items. Pass null to omit.
children	ReactNode	—	Breadcrumbs.Item children. The last item is auto-marked current when no item already sets current.

Breadcrumbs.Item

Name	Type	Default	Description
current	boolean	false	Marks the item as the current page. Auto-applied to the last item when no item explicitly sets it. Adds aria-current="page" and bold styling.
children	ReactNode	—	Item content, typically a Breadcrumbs.Link or plain text.

Breadcrumbs.Link

Name	Type	Default	Description
href	string	—	Anchor href. Omit when using the render-prop form with a framework Link.
childrenrequired	ReactNode \| (props: BreadcrumbsLinkRenderProps) => ReactNode	—	Link label, or a render function that receives ref, className, aria-current, and remaining anchor props.

Breadcrumbs.Ellipsis

Name	Type	Default	Description
label	string	"More"	Screen-reader text announcing collapsed breadcrumb levels.
children	ReactNode	"..."	Ellipsis content (defaults to three dots).

Accessibility

Notes

Current Page

Use the current prop on any Breadcrumbs.Item to mark it as the current page (sets aria-current='page' and bold styling).

Auto-Separator

Separators are inserted automatically between items. Pass separator={<ChevronRight />} to customize, or separator={null} to disable.

Router Integration

Use the render-prop on Breadcrumbs.Link to integrate framework link components (Next.js Link, React Router NavLink). Pass a function as children to receive computed props (ref, className, etc.) and render your custom element.

Source

Install via CLI: pnpm exec dgadd add ui/breadcrumbs.

Highlighted source loads after this disclosure opens. Browse the source repository.

Breadcrumbs

Installation

Usage

Examples

Custom Separator

Custom Link

Ellipsis

Constrained Width

API Reference

Breadcrumbs

Breadcrumbs.Item

Breadcrumbs.Link

Breadcrumbs.Ellipsis

Accessibility

Notes

Current Page

Auto-Separator

Router Integration

Source

View component source (11 files)