Breadcrumb
SaveA breadcrumb trail with thin slash separators, a current page, and a collapsed middle that opens a menu of the hidden steps.
- Category
- Navigation
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Breadcrumb preview
Installation
npx @shakenui/cli add breadcrumbReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add breadcrumb --dry-runUsage
breadcrumb-example.tsx
import {
Breadcrumb,
BreadcrumbItem,
BreadcrumbLink,
BreadcrumbList,
BreadcrumbOverflow,
BreadcrumbPage,
BreadcrumbSeparator,
} from "@/components/shaken/ui/breadcrumb";
export default function BreadcrumbExample() {
return (
<div className="flex w-full max-w-lg flex-col gap-6">
<Breadcrumb aria-label="Settings breadcrumb">
<BreadcrumbList>
<BreadcrumbItem>
<BreadcrumbLink href="#workspace">
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path
d="M2.75 7.1 8 2.75l5.25 4.35v5.65c0 .28-.22.5-.5.5H9.5v-3.5h-3v3.5H3.25a.5.5 0 0 1-.5-.5z"
stroke="currentColor"
strokeWidth="1.5"
strokeLinejoin="round"
/>
</svg>
Northwind
</BreadcrumbLink>
</BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem>
<BreadcrumbLink href="#settings">Settings</BreadcrumbLink>
</BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem>
<BreadcrumbPage>Members</BreadcrumbPage>
</BreadcrumbItem>
</BreadcrumbList>
</Breadcrumb>
<Breadcrumb aria-label="Deployment breadcrumb">
<BreadcrumbList>
<BreadcrumbItem>
<BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
</BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem>
<BreadcrumbOverflow
items={[
{ label: "billing-api", href: "#billing-api" },
{ label: "Environments", href: "#environments" },
{ label: "Production", href: "#production" },
]}
/>
</BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem>
<BreadcrumbLink href="#deployments">Deployments</BreadcrumbLink>
</BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem>
<BreadcrumbPage className="font-mono text-[13px]">dpl_7Hq2xK9</BreadcrumbPage>
</BreadcrumbItem>
</BreadcrumbList>
</Breadcrumb>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| Breadcrumb aria-label | string | "Breadcrumb" | Accessible name of the nav landmark. Change it when a page has more than one trail. |
| BreadcrumbList / BreadcrumbItem | ComponentProps<"ol"> / ComponentProps<"li"> | — | The ordered trail and one step in it. The list wraps onto a second line when space runs out. |
| BreadcrumbLink render | ReactElement | — | Replaces the <a>, for example render={<Link href="/settings" />} for client-side routing. Accepts any anchor attribute. |
| BreadcrumbPage | ComponentProps<"span"> | — | The current page, with aria-current="page". Long titles truncate. |
| BreadcrumbSeparator children | ReactNode | — | Replaces the default slash mark between steps. |
| BreadcrumbOverflow items | { label, href, render? }[] | — | Steps hidden behind the ellipsis button, in trail order. Each opens as a link in a menu. |
| BreadcrumbOverflow aria-label | string | "Show N more pages" | Accessible name of the ellipsis button. |
Accessibility
- Renders a nav landmark named "Breadcrumb" holding an ordered list, so screen readers announce the number of steps and their order.
- The current page is plain text with aria-current="page", not a link to itself.
- Separators are hidden from assistive technology with aria-hidden and role="presentation"; the list order carries the meaning.
- The ellipsis is a real button with an accessible name such as "Show 3 more pages"; Enter, Space, or ArrowDown opens the menu of hidden steps, and the arrow keys move between them.
- Hidden steps are rendered as links inside the menu (role="menuitem" on an <a>), so they can be opened in a new tab.
- Links and the ellipsis show the sky focus ring on keyboard focus. Hover only changes color, and the menu's grow and fade are removed with reduced motion.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/breadcrumb.tsxbreadcrumb- Also installs dropdown-menu@0.2.1registry dependency
- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/breadcrumb/0.1.0.json.
ui/breadcrumb.tsxShowHide
ui/breadcrumb.tsx
"use client";
import { mergeProps } from "@base-ui/react/merge-props";
import { useRender } from "@base-ui/react/use-render";
import type { ComponentProps, ReactElement, ReactNode } from "react";
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "./dropdown-menu";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
const focusRing = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500";
export interface BreadcrumbProps extends ComponentProps<"nav"> {
/** Accessible name of the landmark. Change it when a page has more than one breadcrumb. */
"aria-label"?: string;
}
/** The breadcrumb landmark. Holds a single `BreadcrumbList`. */
export function Breadcrumb({ "aria-label": label = "Breadcrumb", className, ...props }: BreadcrumbProps) {
return <nav aria-label={label} className={cx("min-w-0", className)} {...props} />;
}
/** The ordered trail. Wraps onto a second line when it runs out of room. */
export function BreadcrumbList({ className, ...props }: ComponentProps<"ol">) {
return (
<ol
className={cx(
"m-0 flex min-w-0 list-none flex-wrap items-center gap-x-1 gap-y-1 p-0 text-sm text-zinc-500 dark:text-zinc-400",
className,
)}
{...props}
/>
);
}
/** One step of the trail: a `BreadcrumbLink`, `BreadcrumbPage`, or `BreadcrumbOverflow`. */
export function BreadcrumbItem({ className, ...props }: ComponentProps<"li">) {
return <li className={cx("inline-flex min-w-0 items-center gap-1.5", className)} {...props} />;
}
export interface BreadcrumbLinkProps extends useRender.ComponentProps<"a"> {}
/**
* A link to an ancestor page. Renders an `<a>`; pass `render={<Link href="…" />}` to use your
* router's link component. Hover and focus only change color, so the trail never shifts.
*/
export function BreadcrumbLink({ render, className, ...props }: BreadcrumbLinkProps) {
return useRender({
defaultTagName: "a",
render,
props: mergeProps<"a">(
{
className: cx(
"-mx-1 inline-flex min-w-0 items-center gap-1.5 rounded-md px-1 py-0.5 no-underline",
"transition-colors duration-150 ease-out motion-reduce:transition-none",
"hover:text-zinc-950 dark:hover:text-white",
"[&_svg]:size-4 [&_svg]:shrink-0",
focusRing,
className,
),
},
props,
),
});
}
/** The current page. Not a link; announced with `aria-current="page"`. Long titles truncate. */
export function BreadcrumbPage({ className, ...props }: ComponentProps<"span">) {
return (
<span
aria-current="page"
className={cx(
"inline-flex min-w-0 items-center gap-1.5 truncate font-medium text-zinc-950 dark:text-white [&_svg]:size-4 [&_svg]:shrink-0",
className,
)}
{...props}
/>
);
}
/**
* The mark between steps: a thin forward slash by default. Hidden from assistive technology,
* since the list structure already conveys the order. Pass children to use your own mark.
*/
export function BreadcrumbSeparator({ className, children, ...props }: ComponentProps<"li">) {
return (
<li
role="presentation"
aria-hidden="true"
className={cx("inline-flex items-center text-zinc-950/25 dark:text-white/25 [&_svg]:size-3.5", className)}
{...props}
>
{children ?? (
<svg viewBox="0 0 16 16" fill="none">
<path d="M10.25 2.75 5.75 13.25" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
</svg>
)}
</li>
);
}
export interface BreadcrumbOverflowLink {
/** Visible text of the hidden step. */
label: ReactNode;
/** Destination of the hidden step. */
href: string;
/** Replaces the `<a>` element, for example `<Link href="…" />` for client-side routing. */
render?: ReactElement;
}
export interface BreadcrumbOverflowProps extends Omit<ComponentProps<"button">, "children"> {
/** The steps hidden behind the ellipsis, in trail order. */
items: BreadcrumbOverflowLink[];
/** Accessible name of the ellipsis button. Defaults to "Show N more pages". */
"aria-label"?: string;
}
/**
* Collapses the middle of a long trail into an ellipsis button. Pressing it opens a menu of the
* hidden steps, which are real links, so they keep working with middle-click and the keyboard.
*/
export function BreadcrumbOverflow({ items, "aria-label": label, className, ...props }: BreadcrumbOverflowProps) {
return (
<DropdownMenu>
<DropdownMenuTrigger
aria-label={label ?? `Show ${items.length} more ${items.length === 1 ? "page" : "pages"}`}
className={cx(
"-mx-0.5 inline-flex h-6 w-7 items-center justify-center rounded-md text-zinc-500 dark:text-zinc-400",
"transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none",
"hover:bg-zinc-950/[0.05] hover:text-zinc-950 dark:hover:bg-white/[0.08] dark:hover:text-white",
"data-[popup-open]:bg-zinc-950/[0.06] data-[popup-open]:text-zinc-950 dark:data-[popup-open]:bg-white/[0.09] dark:data-[popup-open]:text-white",
focusRing,
className,
)}
{...props}
>
<svg aria-hidden="true" viewBox="0 0 16 16" fill="currentColor" className="size-4">
<circle cx="3.5" cy="8" r="1.1" />
<circle cx="8" cy="8" r="1.1" />
<circle cx="12.5" cy="8" r="1.1" />
</svg>
</DropdownMenuTrigger>
<DropdownMenuContent align="start" className="min-w-44">
{items.map((item) => (
<DropdownMenuItem key={item.href} render={item.render ?? <a href={item.href} />} className="no-underline">
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path
d="M2.5 4.75v-.5c0-.69.56-1.25 1.25-1.25h2.6l1.4 1.5h4.5c.69 0 1.25.56 1.25 1.25v5.5c0 .69-.56 1.25-1.25 1.25h-8.5c-.69 0-1.25-.56-1.25-1.25z"
stroke="currentColor"
strokeWidth="1.5"
strokeLinejoin="round"
/>
</svg>
<span className="truncate">{item.label}</span>
</DropdownMenuItem>
))}
</DropdownMenuContent>
</DropdownMenu>
);
}