);
}
```
## API reference
### Breadcrumb
Renders a nav labelled "Breadcrumb" and accepts every native attribute.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxItems` | `number` | — | Collapse the trail when it has more items than this (minimum 2). The first item and the last maxItems − 1 stay visible. |
| `color` | `NeonColor` | `inherited` | Palette name or hex. Falls back to --neon-accent, then cyan. |
| `aria-label` | `string` | `"Breadcrumb"` | Name of the navigation landmark. |
### BreadcrumbList
Renders an ol that wraps on narrow screens. Put BreadcrumbItem and BreadcrumbSeparator directly inside it (fragments are fine) so it can collapse them.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes for the list, e.g. a mono font for paths. |
### BreadcrumbItem
Renders an li around one link or the current page.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes for the list item. |
### BreadcrumbLink
Renders an a. Icons inside are sized to the text.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Where the crumb goes. |
| `asChild` | `boolean` | `false` | Merge the link styles onto the single child, such as your router's Link or a button. |
### BreadcrumbPage
The current page. Renders a span with aria-current="page".
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes for the span. |
### BreadcrumbSeparator
Renders a presentational li, hidden from screen readers.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `chevron` | Replaces the chevron, e.g. a slash. |
### BreadcrumbEllipsis
The button that maxItems renders. Exported for building your own overflow, e.g. as a menu trigger.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Show more"` | Accessible name for the icon button. |
| `children` | `ReactNode` | `ellipsis icon` | Replaces the icon. |
## Accessibility
- The trail is an ordered list inside a nav landmark named "Breadcrumb".
- The current page carries aria-current="page" and is not a link.
- Separators are presentational and hidden from screen readers, so the list reads as its links only.
- The collapse button is named for what it reveals, such as "Show 3 more items". After expanding, focus moves to the first revealed link.
- Revealed items slide in with a short stagger; with reduced motion they appear at once.
## Source
`components/ui/breadcrumb.tsx`
```tsx
"use client";
import * as React from "react";
import { ChevronRight, Ellipsis } from "@/components/ui/icons";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
/** The single element in `node`. Server Components can pass it as a lazy reference, which Children resolves. */
function resolveElement
(child) ? child : null;
}
type RenderProp = { asChild?: boolean; render?: React.ReactElement; nativeButton?: boolean; children?: React.ReactNode };
/**
* Base UI spells asChild as `render={}` plus `nativeButton`, and the shadcn CLI rewrites
* asChild into that form in base-* projects. Folds it back into asChild and children.
*/
function fromRenderProp
({ render, nativeButton, ...props }: P): Omit {
void nativeButton; // Only meaningful to Base UI.
if (!render) return props;
const children = props.children === undefined ? render : React.cloneElement(render, undefined, props.children);
return { ...props, asChild: true, children };
}
// Revealed items slide in a few pixels from the ellipsis, one after another.
const keyframes = `@keyframes nk-breadcrumb-reveal{from{opacity:0;transform:translateX(-4px)}}`;
const revealClass =
"motion-safe:[animation:nk-breadcrumb-reveal_220ms_cubic-bezier(0.23,1,0.32,1)_both]";
const BreadcrumbContext = React.createContext<{ maxItems?: number }>({});
type AnyRef = React.Ref | undefined;
function setRef(ref: AnyRef, value: T | null) {
if (typeof ref === "function") ref(value);
else if (ref) (ref as React.RefObject).current = value;
}
// React 19 moved `ref` into props; reading `element.ref` there logs a warning.
function getElementRef(element: React.ReactElement): AnyRef {
if (Number.parseInt(React.version, 10) >= 19) {
return (element.props as { ref?: React.Ref }).ref;
}
return (element as unknown as { ref?: React.Ref }).ref;
}
const LAZY = Symbol.for("react.lazy");
type LazyType = { $$typeof: symbol; _payload: unknown; _init: (payload: unknown) => unknown };
/**
* True when `node` is an element of `component`. Children passed down from a Server Component
* can arrive as lazy references to the client module, so those are resolved first. This file is
* already loaded by the time it runs, so resolving never suspends.
*/
function isElementOf(node: React.ReactNode, component: unknown) {
if (!React.isValidElement(node)) return false;
let type: unknown = node.type;
if (typeof type === "object" && type !== null && (type as LazyType).$$typeof === LAZY) {
try {
type = (type as LazyType)._init((type as LazyType)._payload);
} catch {
return false;
}
}
return type === component;
}
/** Flattens fragments so `items.map(item => <>…)` collapses like plain children. */
function flatten(children: React.ReactNode, prefix = ""): React.ReactNode[] {
return React.Children.toArray(children).flatMap((child) => {
if (!React.isValidElement<{ children?: React.ReactNode }>(child)) return [child];
const key = `${prefix}${child.key ?? ""}`;
if (child.type === React.Fragment) return flatten(child.props.children, key);
return [prefix ? React.cloneElement(child, { key }) : child];
});
}
export interface BreadcrumbProps extends Omit, "color"> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
/**
* Collapse the middle of the trail when it has more items than this. The first item and the
* last `maxItems - 1` stay; the rest fold into an ellipsis button that expands inline.
*/
maxItems?: number;
}
const Breadcrumb = React.forwardRef(
({ className, style, color, maxItems, children, "aria-label": ariaLabel, ...props }, ref) => {
const context = React.useMemo(() => ({ maxItems }), [maxItems]);
return (
);
},
);
Breadcrumb.displayName = "Breadcrumb";
const BreadcrumbList = React.forwardRef>(
({ className, children, ...props }, ref) => {
const { maxItems } = React.useContext(BreadcrumbContext);
const listRef = React.useRef(null);
const mergedRef = React.useCallback(
(node: HTMLOListElement | null) => {
setRef(ref, node);
listRef.current = node;
},
[ref],
);
const focusRevealed = React.useRef(false);
// Remember which trail was expanded, so navigating to a new path collapses again.
const [expandedFor, setExpandedFor] = React.useState(null);
const nodes = flatten(children);
const itemIndexes = nodes.flatMap((node, index) => (isElementOf(node, BreadcrumbItem) ? [index] : []));
const count = itemIndexes.length;
const trail = itemIndexes.map((index) => (nodes[index] as React.ReactElement).key).join("|");
const limit = maxItems == null ? Infinity : Math.max(2, Math.floor(maxItems));
const overflowing = count > limit;
const collapsed = overflowing && expandedFor !== trail;
// Everything between the first item and the trailing items folds away.
const headEnd = overflowing ? itemIndexes[0] : -1;
const tailStart = overflowing ? itemIndexes[count - (limit - 1)] : -1;
const hidden = overflowing ? nodes.slice(headEnd + 1, tailStart) : [];
const isSeparator = (node: React.ReactNode) => isElementOf(node, BreadcrumbSeparator);
const leadingSeparator = isSeparator(hidden[0]) ? hidden[0] : null;
const trailingSeparator =
hidden.length > 1 && isSeparator(hidden[hidden.length - 1]) ? hidden[hidden.length - 1] : null;
React.useEffect(() => {
if (collapsed || !focusRevealed.current) return;
focusRevealed.current = false;
listRef.current
?.querySelector("[data-revealed] a, [data-revealed] button, [data-revealed] [tabindex]")
?.focus();
}, [collapsed]);
let content: React.ReactNode[] = nodes;
if (collapsed) {
const hiddenItems = count - limit;
content = [
...nodes.slice(0, headEnd + 1),
leadingSeparator,
{
focusRevealed.current = true;
setExpandedFor(trail);
}}
/>
,
trailingSeparator &&
React.cloneElement(trailingSeparator as React.ReactElement, { key: "nk-breadcrumb-ellipsis-separator" }),
...nodes.slice(tailStart),
];
} else if (overflowing) {
let step = 0;
content = nodes.map((node, index) => {
const revealed = index > headEnd && index < tailStart && node !== leadingSeparator;
if (!revealed || !React.isValidElement>(node)) return node;
return React.cloneElement(node, {
"data-revealed": "",
className: cn(node.props.className, revealClass),
style: { ...node.props.style, animationDelay: `${step++ * 28}ms` },
} as React.HTMLAttributes);
});
}
return (
{content}
);
},
);
BreadcrumbList.displayName = "BreadcrumbList";
const BreadcrumbItem = React.forwardRef>(
({ className, ...props }, ref) => (
),
);
BreadcrumbItem.displayName = "BreadcrumbItem";
export interface BreadcrumbLinkProps extends React.AnchorHTMLAttributes {
/** Merge the link styles onto the single child element, such as your router's Link. */
asChild?: boolean;
/** Base UI-style asChild: `render={}`. */
render?: React.ReactElement;
/** Accepted for Base UI compatibility; no effect. */
nativeButton?: boolean;
}
const BreadcrumbLink = React.forwardRef(
(raw, ref) => {
const { className, asChild = false, children, ...props } = fromRenderProp(raw);
const child =
asChild ? resolveElement>(children) : null;
const childRef = child ? getElementRef(child) : undefined;
const mergedRef = React.useCallback(
(node: HTMLAnchorElement | null) => {
setRef(ref, node);
setRef(childRef, node);
},
[ref, childRef],
);
const classes = cn(
"inline-flex min-w-0 items-center gap-1.5 rounded-md text-white/55 outline-none",
"transition-[color,text-shadow] duration-150 ease-out hover:text-white/90",
"focus-visible:ring-2 focus-visible:ring-[rgb(var(--neon)/0.6)] focus-visible:ring-offset-2 focus-visible:ring-offset-[#05060a]",
"[&_svg]:size-3.5 [&_svg]:shrink-0",
className,
);
if (child) {
return React.cloneElement(child, {
...props,
...child.props,
className: cn(classes, child.props.className),
onClick: (event: React.MouseEvent) => {
child.props.onClick?.(event);
if (!event.defaultPrevented) props.onClick?.(event as React.MouseEvent);
},
ref: mergedRef,
} as React.HTMLAttributes);
}
return (
{children}
);
},
);
BreadcrumbLink.displayName = "BreadcrumbLink";
const BreadcrumbPage = React.forwardRef>(
({ className, ...props }, ref) => (
),
);
BreadcrumbPage.displayName = "BreadcrumbPage";
const BreadcrumbSeparator = React.forwardRef>(
({ className, children, ...props }, ref) => (