Skip to content
Shaken UI
Sign in

Breadcrumb

Save

A 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 breadcrumb

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add breadcrumb --dry-run

Usage

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

PropTypeDefaultDescription
Breadcrumb aria-labelstring"Breadcrumb"Accessible name of the nav landmark. Change it when a page has more than one trail.
BreadcrumbList / BreadcrumbItemComponentProps<"ol"> / ComponentProps<"li">—The ordered trail and one step in it. The list wraps onto a second line when space runs out.
BreadcrumbLink renderReactElement—Replaces the <a>, for example render={<Link href="/settings" />} for client-side routing. Accepts any anchor attribute.
BreadcrumbPageComponentProps<"span">—The current page, with aria-current="page". Long titles truncate.
BreadcrumbSeparator childrenReactNode—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-labelstring"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.tsxShow
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>
  );
}