Breadcrumb

A hierarchical navigation trail that shows the user's location within a site or app.

stable
since v0.1.0
2.5 kB
navigation
breadcrumb
accessible

Preview

tsx

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Home</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/components">Components</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem isCurrent>
        <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
      </BreadcrumbItem>
    </Breadcrumb>
  );
}

Usage

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
} from "@arshad-shah/cynosure-react";

<Breadcrumb>
  <BreadcrumbItem>
    <BreadcrumbLink href="/">Home</BreadcrumbLink>
  </BreadcrumbItem>
  <BreadcrumbItem>
    <BreadcrumbLink href="/components">Components</BreadcrumbLink>
  </BreadcrumbItem>
  <BreadcrumbItem isCurrent>
    <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
  </BreadcrumbItem>
</Breadcrumb>

Separators are interleaved between BreadcrumbItem children automatically — you don’t need to add them yourself.

Variants

Custom separator

Pass a separator ReactNode to swap the default chevron for any glyph.

Preview

Open

tsx

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Breadcrumb separator={<span aria-hidden="true">/</span>}>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Home</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem isCurrent>
        <BreadcrumbPage>Getting started</BreadcrumbPage>
      </BreadcrumbItem>
    </Breadcrumb>
  );
}

Collapsed middle items

Set maxItems to collapse the middle of a long trail into a BreadcrumbEllipsis. Tune which items stay visible at each end with itemsBeforeCollapse (default 1) and itemsAfterCollapse (default 2).

Preview

Open

tsx

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Breadcrumb maxItems={4} itemsBeforeCollapse={1} itemsAfterCollapse={2}>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Home</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/library">Library</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/library/foundations">Foundations</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/library/foundations/colors">Colors</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/library/foundations/colors/tokens">Tokens</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem isCurrent>
        <BreadcrumbPage>Accent scale</BreadcrumbPage>
      </BreadcrumbItem>
    </Breadcrumb>
  );
}

With a leading icon

BreadcrumbLink accepts any children, so an inline SVG renders alongside the label.

Preview

Open

tsx

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
} from '@arshad-shah/cynosure-react';

const HomeIcon = () => (
  <svg
    aria-hidden="true"
    width="14"
    height="14"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2h-4a2 2 0 0 1-2-2v-5h-2v5a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
  </svg>
);

export default function Example() {
  return (
    <Breadcrumb>
      <BreadcrumbItem>
        <BreadcrumbLink
          href="/"
          style={{ display: 'inline-flex', alignItems: 'center', gap: '0.375rem' }}
        >
          <HomeIcon />
          Home
        </BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbItem isCurrent>
        <BreadcrumbPage>Cynosure</BreadcrumbPage>
      </BreadcrumbItem>
    </Breadcrumb>
  );
}

API

PropTypeDefaultDescription

separator

ReactNode

—

Element rendered between items. Defaults to a small Lucide `ChevronRight` glyph.

maxItems

number

—

Collapse middle items when the total exceeds this count. Omit for an uncollapsed trail.

itemsBeforeCollapse

number

Items kept visible at the start of the trail when collapsing.

itemsAfterCollapse

number

Items kept visible at the end of the trail when collapsing.

renderCollapsed

((hiddenItems: ReactElement<unknown, string | JSXElementConstructor<any>>[]) => ReactNode)

—

Custom collapsed-items trigger. Defaults to a `BreadcrumbEllipsis` button — replace with e.g. a `DropdownMenu` listing the hidden links.

aria-label

string

"Breadcrumb"

Accessible label on the wrapping `<nav>`.

Accessibility

The root renders a <nav> with aria-label="Breadcrumb" (override via the aria-label prop).
Items render as <li> inside an <ol> so the trail order is exposed to assistive tech.
BreadcrumbItem carries aria-current="page" when isCurrent is set; BreadcrumbPage always carries aria-current="page".
Separators are <li role="presentation" aria-hidden="true"> so they don’t pollute the announcement.
The collapsed-items trigger is a real <button> (rendered via IconButton) with "Show more" as its default label.

Recipes

Pair <BreadcrumbItem isCurrent> with <BreadcrumbPage> so both the <li> and the inner element announce the current page.
Use renderCollapsed to wire the ellipsis to a DropdownMenu listing the hidden links.
Lower maxItems (e.g. 3) on mobile breakpoints to shorten the trail.
Replace the default chevron with a / glyph for a more typographic look.