Skip to content

Breadcrumb

Links back up the trail to where this page sits, with a long trail folded into a popover.

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-default">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#posts">Posts</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Why the spring update took so long</span></li>
  </ol>
</nav>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/breadcrumb.css";
import { enhance } from "capsomer/behavior/breadcrumb";

enhance();

Usage

<nav class="cap-breadcrumb" aria-label="Breadcrumb">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="/admin">Admin</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="/admin/posts">Posts</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Edit</span></li>
  </ol>
</nav>
<li class="cap-breadcrumb-item" data-collapsed>
  <span data-cap="popover">
    <button type="button" class="cap-breadcrumb-ellipsis" popovertarget="bc-more" aria-haspopup="dialog" aria-expanded="false" aria-label="Show 2 more levels"><svg aria-hidden="true">...</svg></button>
    <div class="cap-popover" id="bc-more" popover="auto" role="dialog" aria-label="More levels" data-side="bottom" data-align="start" data-size="auto" data-flush>
      <ul class="cap-breadcrumb-more">
        <li><a class="cap-breadcrumb-more-link" href="/sites">Sites</a></li>
      </ul>
    </div>
  </span>
</li>
<Breadcrumb
  items={[{ label: "Admin", href: "/admin" }, { label: "Posts", href: "/admin/posts" }, { label: "Edit" }]}
  maxItems={4}
  renderLink={({ href, className, children }) => <Link to={href} className={className}>{children}</Link>}
/>

Examples

Two levels, and hover on a link

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-two">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#sites">Sites</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">example.com</span></li>
  </ol>
</nav>

Long names wrap

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-long">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#media">Media library</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#campaign" id="bc-long-link">Autumn 2026 community garden field survey photographs from the east park sites</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page" id="bc-long-page">IMG_4821 north bed of the community garden at dawn, plot 3 of 12, photographed after eighteen hours of steady rain, the second visit of the spring survey</span></li>
  </ol>
</nav>

A long trail folded in the HTML: the middle levels are links in a popover

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-folded" data-cap="breadcrumb">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
    <li class="cap-breadcrumb-item" data-collapsed>
      <span data-cap="popover">
        <button type="button" class="cap-breadcrumb-ellipsis" popovertarget="bc-folded-more" aria-haspopup="dialog" aria-expanded="false" aria-label="Show 2 more levels"><svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="3" cy="8" r="1.4" fill="currentColor" /><circle cx="8" cy="8" r="1.4" fill="currentColor" /><circle cx="13" cy="8" r="1.4" fill="currentColor" /></svg></button>
        <div class="cap-popover" id="bc-folded-more" popover="auto" role="dialog" aria-label="More levels" data-side="bottom" data-align="start" data-size="auto" data-flush>
          <ul class="cap-breadcrumb-more">
            <li><a class="cap-breadcrumb-more-link" href="#sites">Sites</a></li>
            <li><a class="cap-breadcrumb-more-link" href="#example">example.com</a></li>
          </ul>
        </div>
      </span>
    </li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#runs">Runs</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">job_7c21</span></li>
  </ol>
</nav>

The whole trail in the HTML; script folds it (data-max-items="4")

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-auto" data-cap="breadcrumb" data-max-items="4">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#media">Media library</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#2026">2026</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#september">September</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#field-survey">Field survey</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Photo 3</span></li>
  </ol>
</nav>

A trail that is not longer than the limit stays whole

<nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-short" data-cap="breadcrumb" data-max-items="4">
  <ol class="cap-breadcrumb-list">
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
    <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#mentions">Mentions</a></li>
    <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Unverified</span></li>
  </ol>
</nav>

In a narrow space the trail wraps

<div class="breadcrumb-narrow-box">
  <nav class="cap-breadcrumb" aria-label="Breadcrumb" id="bc-narrow">
    <ol class="cap-breadcrumb-list">
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#guides">Guides</a></li>
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#setup">Setup</a></li>
      <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Getting started</span></li>
    </ol>
  </nav>
</div>

Comfortable density

<div data-density="comfortable">
  <nav class="cap-breadcrumb" aria-label="Density sample" id="bc-comfortable">
    <ol class="cap-breadcrumb-list">
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
      <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">Posts</span></li>
    </ol>
  </nav>
</div>

The folded levels, open

<main class="specimen-page" tabindex="-1">
  <h1>Job run</h1>
  <nav class="cap-breadcrumb" aria-label="Breadcrumb" data-cap="breadcrumb">
    <ol class="cap-breadcrumb-list">
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#admin">Admin</a></li>
      <li class="cap-breadcrumb-item" data-collapsed>
        <span data-cap="popover" data-specimen-open>
          <button type="button" class="cap-breadcrumb-ellipsis" popovertarget="bc-open-more" aria-haspopup="dialog" aria-expanded="false" aria-label="Show 2 more levels"><svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="3" cy="8" r="1.4" fill="currentColor" /><circle cx="8" cy="8" r="1.4" fill="currentColor" /><circle cx="13" cy="8" r="1.4" fill="currentColor" /></svg></button>
          <div class="cap-popover" id="bc-open-more" popover="manual" role="dialog" aria-label="More levels" data-side="bottom" data-align="start" data-size="auto" data-flush>
            <ul class="cap-breadcrumb-more">
              <li><a class="cap-breadcrumb-more-link" href="#sites">Sites</a></li>
              <li><a class="cap-breadcrumb-more-link" href="#example">example.com</a></li>
            </ul>
          </div>
        </span>
      </li>
      <li class="cap-breadcrumb-item"><a class="cap-breadcrumb-link" href="#runs">Runs</a></li>
      <li class="cap-breadcrumb-item"><span class="cap-breadcrumb-page" aria-current="page">job_7c21</span></li>
    </ol>
  </nav>
</main>

API reference

Breadcrumb

PropTypeRequiredDoes
itemsBreadcrumbItem[]YesThe trail, first level to current page. Fewer than two levels renders nothing: a hub has no trail to show.
maxItemsnumberKeep the first level and the last (maxItems - 1); the rest fold into a popover of links.
minItemsnumberThe fewest levels that draw a trail (2 by default). A site whose trail leaves out the home page, which its header already links, passes its structured data's minimum less one, so the page and its BreadcrumbList agree.
labelstring
renderLink(props: { href: string; className: string; children: ReactNode }) => ReactNodeDraw a level's link with the app's router link: receives the class and the content.

Functions

FunctionSignatureDoes
foldedLevels(count: number, max: number): number[]Which levels fold: none unless the trail is longer than max and at least two levels would go (one level is no shorter than the button that replaces it). The first level and the last max - 1 stay. Returns the positions that fold, a run in the middle.
collapse(nav: HTMLElement, max: number): (() => void) | nullFolds a trail now. Returns a function that puts the levels back, or null when nothing folds.
enhance(root?: ParentNode): () => voidAttaches every [data-cap="breadcrumb"] under root not yet attached: folds a trail that has data-max-items, and attaches the popover of a folded item. Returns a function that detaches them (a folded trail is put back).

Parts and data attributes

ClassIs
.cap-breadcrumbthe root
.cap-breadcrumb-ellipsisa part
.cap-breadcrumb-itema part
.cap-breadcrumb-linka part
.cap-breadcrumb-lista part
.cap-breadcrumb-morea part
.cap-breadcrumb-more-linka part
.cap-breadcrumb-pagea part
StateRead from
:focus-visiblethe platform
:hoverthe platform
:visitedthe platform
[aria-current="page"]an attribute
[aria-expanded="true"]an attribute

Accessibility

KeyDoes
Tab, Shift+TabMoves through the links and the folded-levels button in order; the current page is not a stop
EnterFollows the focused link
Enter, Space on the folded-levels buttonOpens the popover; focus moves to its first link
Tab, Shift+Tab in the popoverMoves between its links; tabbing past the last closes it
EscCloses the popover; focus returns to the button
  • A nav named "Breadcrumb" (use another name if a page has two) holding an ol. The current page is aria-current="page".
  • The folded button is named for what it does ("Show 2 more levels"); it has aria-haspopup="dialog" and aria-expanded. The popover is a dialog named "More levels".
  • Link text 4.5:1 on the page; the current page 4.5:1; the separator is decorative.
  • Each link and the button are at least var(--target) tall and wide. Forced colors draw the separator in CanvasText.