Breadcrumbs
Compact path navigation with optional collapsed middle items.
API Reference
Original primitive API
Behavior, accessibility details, and low-level props are documented by Base UI.
Basic
import { Breadcrumbs } from "moduix";export function BreadcrumbsDemo() { return ( <Breadcrumbs items={[ { label: "Home", href: "/" }, { label: "Engineering", href: "/engineering" }, { label: "Backend", href: "/engineering/backend" }, { label: "Golang", href: "/engineering/backend/golang" }, { label: "Vacancies", href: "/vacancies" }, { label: "Go Developer" }, ]} /> );}Full list of component variables available for project-level overrides.
| Property | Default | Description |
|---|---|---|
| --breadcrumbs-color | var(--color-muted-foreground) | Controls base breadcrumbs text color. |
| --breadcrumbs-ellipsis-bg | transparent | Controls collapsed trigger background. |
| --breadcrumbs-ellipsis-bg-hover | var(--color-accent) | Controls collapsed trigger hover background. |
| --breadcrumbs-ellipsis-border | none | Controls collapsed trigger border. |
| --breadcrumbs-ellipsis-color | var(--breadcrumbs-color, var(--color-muted-foreground)) | Controls collapsed trigger text color. |
| --breadcrumbs-ellipsis-color-hover | var(--color-foreground) | Controls collapsed trigger hover text color. |
| --breadcrumbs-ellipsis-padding-x | 0.2rem | Controls collapsed trigger horizontal padding. |
| --breadcrumbs-ellipsis-radius | var(--radius-sm) | Controls collapsed trigger radius. |
| --breadcrumbs-ellipsis-size | 1.5rem | Controls collapsed trigger size. |
| --breadcrumbs-ellipsis-transition | var(--transition-default) | Controls collapsed trigger transition. |
| --breadcrumbs-focus-ring-color | var(--color-ring) | Controls focus ring color. |
| --breadcrumbs-focus-ring-width | var(--border-width-sm) | Controls focus ring width. |
| --breadcrumbs-font-size | var(--text-sm) | Controls breadcrumbs font size. |
| --breadcrumbs-gap | var(--spacing-1) | Controls spacing between breadcrumb parts. |
| --breadcrumbs-item-max-width | 16rem | Controls max width of each breadcrumb item. |
| --breadcrumbs-line-height | var(--line-height-text-sm) | Controls breadcrumbs line height. |
| --breadcrumbs-link-color | var(--color-muted-foreground) | Controls breadcrumb link color. |
| --breadcrumbs-link-color-hover | var(--color-foreground) | Controls breadcrumb link hover color. |
| --breadcrumbs-link-radius | var(--radius-sm) | Controls breadcrumb link radius. |
| --breadcrumbs-link-text-decoration | none | Controls breadcrumb link text decoration. |
| --breadcrumbs-link-text-decoration-hover | none | Controls breadcrumb link hover text decoration. |
| --breadcrumbs-link-transition | var(--transition-default) | Controls breadcrumb link transition. |
| --breadcrumbs-link-underline-offset | 0.2em | Controls breadcrumb link underline offset. |
| --breadcrumbs-max-width | 100% | Controls max width of breadcrumbs root. |
| --breadcrumbs-page-color | var(--color-foreground) | Controls current page breadcrumb color. |
| --breadcrumbs-page-font-weight | var(--weight-medium) | Controls current page breadcrumb font weight. |
| --breadcrumbs-popup-bg | var(--color-popover) | Controls collapsed menu background. |
| --breadcrumbs-popup-border-color | var(--color-border) | Controls collapsed menu border color. |
| --breadcrumbs-popup-border-width | var(--border-width-sm) | Controls collapsed menu border width. |
| --breadcrumbs-popup-color | var(--color-popover-foreground) | Controls collapsed menu text color. |
| --breadcrumbs-popup-item-bg | transparent | Controls collapsed menu item background. |
| --breadcrumbs-popup-item-bg-highlighted | var(--color-accent) | Controls highlighted collapsed item background. |
| --breadcrumbs-popup-item-bg-hover | var(--breadcrumbs-popup-item-bg-highlighted) | Controls collapsed menu item hover background. |
| --breadcrumbs-popup-item-border | none | Controls collapsed menu item border. |
| --breadcrumbs-popup-item-color | inherit | Controls collapsed menu item text color. |
| --breadcrumbs-popup-item-font-size | var(--text-xs) | Controls collapsed menu item font size. |
| --breadcrumbs-popup-item-line-height | var(--line-height-text-xs) | Controls collapsed menu item line height. |
| --breadcrumbs-popup-item-min-height | 1.75rem | Controls collapsed menu item min height. |
| --breadcrumbs-popup-item-padding-x | 0.5rem | Controls collapsed menu item horizontal padding. |
| --breadcrumbs-popup-item-padding-y | 0.25rem | Controls collapsed menu item vertical padding. |
| --breadcrumbs-popup-item-radius | var(--radius-sm) | Controls collapsed menu item radius. |
| --breadcrumbs-popup-item-transition | var(--transition-default) | Controls collapsed menu item transition. |
| --breadcrumbs-popup-max-width | 16rem | Controls collapsed menu max width. |
| --breadcrumbs-popup-min-width | 9rem | Controls collapsed menu min width. |
| --breadcrumbs-popup-padding | var(--spacing-1) | Controls collapsed menu inner padding. |
| --breadcrumbs-popup-radius | var(--radius-md) | Controls collapsed menu radius. |
| --breadcrumbs-popup-scale | var(--scale-popup) | Controls collapsed menu enter/exit scale. |
| --breadcrumbs-popup-shadow | var(--shadow-md) | Controls collapsed menu shadow. |
| --breadcrumbs-popup-transition | var(--transition-default) | Controls collapsed menu enter/exit transition. |
| --breadcrumbs-separator-color | var(--color-muted-foreground) | Controls separator color. |
Interactive variables scoped for docs preview without changing size scale tokens.
| Property | Value | Default | Description |
|---|---|---|---|
| --breadcrumbs-ellipsis-bg-hover | var(--color-accent) | Controls collapsed trigger hover background. | |
| --breadcrumbs-item-max-width | 16rem | Controls max width of each breadcrumb item. | |
| --breadcrumbs-link-color | var(--color-muted-foreground) | Controls breadcrumb link color. | |
| --breadcrumbs-link-color-hover | var(--color-foreground) | Controls breadcrumb link hover color. | |
| --breadcrumbs-popup-item-bg-hover | var(--breadcrumbs-popup-item-bg-highlighted) | Controls collapsed menu item hover background. | |
| --breadcrumbs-popup-item-font-size | var(--text-xs) | Controls collapsed menu item font size. | |
| --breadcrumbs-separator-color | var(--color-muted-foreground) | Controls separator color. |
Anatomy
Breadcrumbs renders semantic nav and ol structure for path navigation.
When the path is long, intermediate items can collapse into an ellipsis trigger and
open a compact Base UI menu popup.
Breadcrumbs
└─ list
├─ item link
├─ separator
├─ collapsed menu trigger (optional)
├─ separator
└─ current page item| Part | Role |
|---|---|
Breadcrumbs | Root navigation region with aria label and path layout. |
item | Breadcrumb segment, rendered as link or current-page text. |
separator | Visual delimiter between visible segments. |
collapsed menu trigger | Ellipsis control shown when maxItems collapses middle segments. |
collapsed menu popup | Compact list of hidden segments built with Base UI Menu. |
The component keeps all visible segments on one line and clamps long labels, so the breadcrumb row stays compact.
Composition
Use the items array to describe the path. Each item can be a plain segment or a link
(href). For framework routing, pass render on item and return your own link element
(for example Next.js Link) while preserving the provided className and children.
Use maxItems with itemsBeforeCollapse and itemsAfterCollapse to control how many
segments stay visible before and after the collapsed menu.
When collapsed items are enabled, you can style hidden internal parts through classNames
(ellipsisTrigger, popup, popupItem, portal, positioner) and pass behavior props
to those same slots through slotProps.
Examples
Collapsed Path
Collapse intermediate path segments into an ellipsis menu.
import { Breadcrumbs } from "moduix";export function BreadcrumbsCollapsedDemo() { return ( <Breadcrumbs maxItems={4} items={[ { label: "Home", href: "/" }, { label: "Engineering", href: "/engineering" }, { label: "Backend", href: "/engineering/backend" }, { label: "Golang", href: "/engineering/backend/golang" }, { label: "Vacancies", href: "/vacancies" }, { label: "Go Developer" }, ]} /> );}Custom Separator
Replace the default / separator with your own symbol or icon.
import { Breadcrumbs, SeparatorMarkIcon } from "moduix";export function BreadcrumbsSeparatorDemo() { return ( <Breadcrumbs separator={<SeparatorMarkIcon style={{ width: "0.75rem", height: "0.25rem" }} />} items={[ { label: "Home", href: "/" }, { label: "Vacancies", href: "/vacancies" }, { label: "Go Developer" }, ]} /> );}Long Current Label
Current item text is clamped to one line, so long labels do not wrap and break layout.
import { Breadcrumbs } from "moduix";export function BreadcrumbsLongLabelDemo() { return ( <Breadcrumbs items={[ { label: "Home", href: "/" }, { label: "Vacancies", href: "/vacancies" }, { label: "Go lang developer to production team with cross-functional ownership and platform support", }, ]} /> );}Framework Links
Use render to integrate external routing links while keeping breadcrumb styles.
import { Breadcrumbs } from "moduix";import Link from "next/link";export function BreadcrumbsWithNextLinkDemo() { return ( <Breadcrumbs maxItems={3} items={[ { label: "Home", href: "/", render: ({ href, className, children, ...props }) => ( <Link href={href ?? "/"} className={className} {...props}> {children} </Link> ), }, { label: "Engineering", href: "/engineering", render: ({ href, className, children, ...props }) => ( <Link href={href ?? "/engineering"} className={className} {...props}> {children} </Link> ), }, { label: "Backend", href: "/engineering/backend", render: ({ href, className, children, ...props }) => ( <Link href={href ?? "/engineering/backend"} className={className} {...props}> {children} </Link> ), }, { label: "Vacancies", href: "/vacancies" }, { label: "Go Developer" }, ]} /> );}Collapsed Menu Slots
Use classNames and slotProps to customize the collapsed trigger and popup internals.
import { Breadcrumbs } from "moduix";export function BreadcrumbsSlotsDemo() { return ( <Breadcrumbs maxItems={3} items={[ { label: "Home", href: "/" }, { label: "Engineering", href: "/engineering" }, { label: "Backend", href: "/engineering/backend" }, { label: "Vacancies", href: "/vacancies" }, { label: "Go Developer" }, ]} classNames={{ ellipsisTrigger: styles.ellipsisTrigger, popup: styles.popup, popupItem: styles.popupItem, }} slotProps={{ positioner: { sideOffset: 6 }, popup: { "aria-label": "Hidden breadcrumb links" }, }} /> );}