Design breadcrumbs

Requirements: what a breadcrumb is for

A breadcrumb is a short row of links near the top of a page that shows where that page sits in the site's hierarchy: Home, then Electronics, then Laptops, then the laptop you are looking at. Each link takes you up one or more levels. The name comes from the fairy tale where children drop crumbs to find their way home.

It looks like a five minute task: map an array to links with a slash between them. A senior answer treats the breadcrumb as a small view of the app's hierarchy, fed by the router and the data, and shared by every product team. This chapter settles what the trail means and what we must support, then names what makes it hard.

Three kinds of breadcrumb, and only one is right

First settle what the trail means. People use the word for three different things, and mixing them is the most common design mistake.

A location trail has two big properties. It is deterministic: the same URL gives the same trail, so the server can render it and a search engine can read it. And it is about the parent chain, not about time, so it stays correct when a visitor arrives from a search result deep in the site, which is exactly when they need it most.

Questions to ask first

Functional requirements

• Show the ancestors of the current page as links, from the root down, and the current page as the last item.
• Build the trail from the route config, from an item's ancestor chain in the API, or from both.
• Name id segments with real labels, with a stable placeholder while they load.
• Fit any trail into the space it has: collapse the middle into a menu, shorten long labels, or show only a link to the parent.
• Emit BreadcrumbList structured data for public pages, matching the visible trail.
• Allow the router's Link component, a custom separator, and translated labels.

Non-functional requirements

• Accessible: WCAG 2.2 AA. A labelled nav landmark, the current page marked for screen readers, visible focus, targets at least 24 by 24 CSS pixels.
• Stable: no layout shift when labels arrive. The trail reserves its height from the first paint.
• Small: under 3 KB gzipped for the component; the overflow menu loads with it, not on demand, because it is tiny.
• Correct: the trail updates on every client side navigation and never shows the previous page's parents.

Out of scope

• The folder tree in a sidebar: that is a tree view, with its own keyboard model (see the tree view guide).
• Filter chips and category facets (see the search results page and Amazon guides).
• The main site menu and page level navigation such as tabs or pagination.

What makes a small trail hard

Five properties of the problem drive every later decision. Name them early in an interview: it shows you see past the slash separated list.

1. The hierarchy is split between the URL and the data. The route /orgs/:orgId/projects/:projectId/settings has five segments, and the router knows every level. A Drive folder 12 levels deep has one URL segment, /folders/abc123; its 11 ancestors exist only in the database.
2. Segments are ids, not names. The URL says 42 and 7; the trail must say Acme Inc and Billing API. Every id is a lookup that takes time, can fail, and can return an 80 character name.
3. Width is unknown and small. A 9 level folder trail with short names (about 7 characters each) needs about 620 pixels at 14 pixel text, and long names double that. A 360 pixel phone gives you about 330. Something must give, and what gives decides whether the user can still reach the grandparent folder.
4. It is a landmark that repeats on every page. Screen reader users hear it on every page and can jump to it. It must be named once, marked once, and not announce slashes as "slash, slash, slash".
5. It is shared and public. Forty teams use it, with two routers. Public pages send the same trail to Google as structured data, and Google expects that markup to match what the page shows.

Notice what is not on the list: rendering speed. A trail has at most about 15 links. The hard parts are correctness (the right trail, the right names), fit (on any width) and meaning (for screen readers and crawlers). The chapters follow that order.

Deriving the trail: routes, data, or both

The component draws a list. The real design question is who builds the list. Start with the naive answer and break it.

The naive approach: split the URL

Take location.pathname, split it on slashes, and make one crumb per segment: /orgs/42/projects/7/settings becomes orgs, 42, projects, 7, settings. It takes 6 lines and it fails in four ways at once.

• Ids as labels. The user sees 42 and 7, not Acme Inc and Billing API.
• Dead links. The segment orgs makes a link to /orgs, which may not be a page at all, so it returns a 404.
• Missing levels. /drive/folders/abc123 gives three crumbs, but the folder is 12 levels deep. The 11 ancestor folders are not in the URL.
• Wrong grouping. /docs/2024/release-notes might be one page with a date in its path, not three levels.

// routes: crumbs live next to paths
{ path: "orgs/:orgId", loader: orgLoader,
  handle: { crumb: (d: Org) => ({ label: d.name }) },
  children: [{ path: "projects/:projectId", loader: projectLoader,
    handle: { crumb: (d: Project) => ({ label: d.name }) } }] }

// hook: from root to leaf, keep matches that declare a crumb
export function useRouteTrail(): Crumb[] {
  return useMatches()
    .filter((m) => m.handle?.crumb)
    .map((m) => ({ href: m.pathname, ...m.handle.crumb(m.loaderData) }));
}

The same idea works in Next.js. useSelectedLayoutSegments is a client hook, so a small client component inside a layout calls it to read the active segments below that layout. A server layout or page can fetch the item and its ancestors before sending HTML, so the trail arrives already named. Either way, the label for org 42 comes from the loader that already fetched org 42 for the page.

That is the key move: the crumb reuses the page's data, so it costs no extra request most of the time.

Naming dynamic segments

Sometimes the label is not in the page's data. A deep link to /orgs/42/projects/7/settings loads the settings form, which knows the project but maybe not the org's display name. Now each unnamed id needs a lookup. Three rules keep it cheap and calm.

• One batched request. Ask for every missing label at once (GET /labels?ids=org:42,project:7), not one request per crumb. Two to five ids in about 80 ms instead of five round trips.
• A cache keyed by type and id. Labels change rarely, so keep them in the server state cache for 5 minutes and reuse them across pages. Seed it from every list you load: a project list already has 50 names.
• A stable placeholder. While the label loads, show a skeleton bar of a fixed width (about 80 pixels) inside a non-link item, never the raw id. The bar has the same height as text, so nothing moves when the name arrives.

If the lookup fails, show a generic fallback ("Project") as a working link, since the href is known from the route. The trail must never block the page or throw: it is secondary navigation. If the item was deleted or the user lost access, the page itself shows the error; the crumb just falls back.

Items with two parents

A ThinkPad sits in Electronics / Laptops and in Deals / Back to School. A Drive file can be shared into a folder the viewer doesn't own. The trail shows one path, so which one?

No JSON-LD: a logged in page, nothing for a crawler.

Markup and accessibility: a landmark, a list, and one current page

A breadcrumb has no keyboard interaction of its own: it is links in a row, and Tab moves through them. That makes the markup the whole accessibility story. The WAI-ARIA Authoring Practices Guide (APG) breadcrumb pattern asks for three things: a navigation landmark, a label on that landmark, and aria-current="page" on the link to the current page.

<nav aria-label="Breadcrumb" class="crumbs">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/electronics">Electronics</a></li>
    <li><a href="/electronics/laptops">Laptops</a></li>
    <li><a href="/p/thinkpad-x1" aria-current="page">ThinkPad X1</a></li>
  </ol>
</nav>

Is the current page a link?

Separators that screen readers don't read

If the slash is text in the markup, a screen reader says "Home, slash, Electronics, slash, Laptops". The nav label already says this is a trail, so the slashes are noise. Three ways to keep them out, from best to worst:

1. A CSS border or background image on each li after the first, as the APG example does with a skewed border. Nothing to read at all.
2. An inline SVG chevron with aria-hidden="true", when the design wants an icon. Easy to theme and to flip for right to left.
3. CSS generated content with empty alternative text, content: "/" / "". Plain content: "/" is not safe: generated content is often read aloud. Test the alternative text syntax with your screen readers.

.crumbs ol { display: flex; align-items: center; min-inline-size: 0;
  list-style: none; margin: 0; padding: 0; }  /* one line; collapse handles overflow */
.crumbs li { display: flex; align-items: center; min-inline-size: 0; }
.crumbs li + li::before {
  content: "/" / "";                          /* visible, not read */
  margin-inline: var(--cf-space-200);
  color: var(--cf-color-text-muted);
}
.crumbs a, .crumbs [aria-current] {
  display: block; max-inline-size: 200px;     /* one huge name can't take the row */
  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
  min-block-size: 24px; line-height: 24px;    /* WCAG 2.5.8 minimum */
  padding-inline: var(--cf-space-050);
}
.crumbs a:focus-visible {
  outline: 2px solid var(--cf-color-focus-ring); outline-offset: 2px;
}
.crumbs svg.sep:dir(rtl) { transform: scaleX(-1); }

Target size, focus and right to left

Breadcrumb links are small text in a tight row, which is what WCAG 2.2 success criterion 2.5.8, Target Size (Minimum), is about. At level AA, a pointer target must be at least 24 by 24 CSS pixels, with a few exceptions. The spacing exception passes a smaller target if a 24 pixel circle centered on it touches no other target and no other small target's circle. The inline exception covers links inside a sentence, which a breadcrumb row is not.

A link in 14 pixel text is about 20 pixels tall. In a single row with separators between links, most links pass on spacing alone, but that depends on margins nobody re-checks when the design changes, and the W3C's guidance recommends meeting the minimum size anyway. So the CSS above gives every link a minimum height of 24 pixels and a little inline padding. On touch layouts, aim higher for the one or two items you keep (44 pixels is the enhanced level, 2.5.5, at AAA).

Focus must be visible on every link and on the overflow button: use :focus-visible with a 2 pixel outline that does not get clipped by an overflow: hidden parent (a common bug once you add truncation). For right to left languages, the list order flips by itself because flex follows the dir attribute: in Arabic the root sits on the right. A slash needs no change, but a chevron or arrow must be mirrored, or it points back toward the root. The rtl layouts lesson covers logical properties in general.

Overflow: fitting 9 levels into 330 pixels

Take a real trail: My Drive / Clients / Acme Inc / 2026 / Q3 / Contracts / Signed / Legal review / Final. Nine items and 61 characters, about 7 per label. At 14 pixel text a character is about 7.5 pixels wide, so the labels need about 460 pixels, plus 8 separators at about 20 pixels each: roughly 620 pixels. A 360 pixel phone, minus 16 pixels of padding each side, leaves 328, so only about half the trail fits, and real folder names are often longer.

Measure the width, or use fixed rules?

The simple way is a rule: maxItems of 4 below 600 pixels, 8 above (MUI's maxItems defaults to 8, with itemsBeforeCollapse and itemsAfterCollapse both 1). Rules are predictable and need no JavaScript, but they are wrong both ways: four long names overflow a phone, and nine short ones would have fit. Because labels are data (folder names typed by users), only measuring is always right.

1. Render every item once into a hidden measuring row (visibility: hidden, position: absolute, same font) and record the widths of each item, the separator and the ellipsis button. Re-measure only when labels or fonts change.
2. Watch the container with a ResizeObserver. On each size change, compute how many items fit. A few additions, cheap even on every frame of a drag.
3. Keep the first item and the last one. Add items back from the end (the nearest ancestors first, since they are the most useful), then from the start, until the next one would not fit.

export function fit(widths: number[], avail: number,
  sep = 20, ellipsis = 32): { start: number; end: number } | null {
  const n = widths.length;
  const all = widths.reduce((s, w) => s + w, 0) + sep * (n - 1);
  if (all <= avail || n < 3) return null;   // fits, or nothing to hide
  let used = widths[0] + widths[n - 1] + ellipsis + sep * 2;
  let start = 1, end = n - 1;               // hidden range is [start, end)
  while (end - 1 > start) {                 // add ancestors from the end first
    const w = widths[end - 1] + sep;
    if (used + w > avail) break;
    used += w; end--;
  }
  while (start < end - 1) {                 // then from the start
    const w = widths[start] + sep;
    if (used + w > avail) break;
    used += w; start++;
  }
  return { start, end };
}

Server rendering has no width to measure. Send the server HTML with a conservative rule (first item, menu, last two, labels capped) that fits most phones, then let the client measure and correct it. Showing more or fewer items on the same line causes no layout shift, because the height doesn't change.

The collapsed menu

MUI's ellipsis button expands the whole trail inline (its label defaults to "Show path"). That is fine on desktop, but on a phone it brings back the wrapping we avoided, so a popup list suits narrow screens better.

Build it as a disclosure: a real button that shows and hides a region, with aria-expanded telling screen readers whether it is open. Give it an accessible name like "Show 6 more levels", and let it open the hidden ancestors as a list of links, in trail order. It is navigation, so plain links in a list are the right semantics. The menu role, with its arrow key model, is for application commands (the dropdown select guide covers menu buttons in depth).

• Enter or Space on the button opens the list and moves focus to its first link. Tab moves through the links; Escape closes it and returns focus to the button.
• Clicking outside or tabbing out closes it.
• The links keep their tree order from top to bottom (Clients, Acme Inc, 2026...), so the list reads like the trail.
• In the DOM, the button sits in its own li, in the place of the hidden items, so the list still announces a sensible count.

Long labels and the title attribute

A label cut with text-overflow: ellipsis keeps its full text in the DOM, so screen readers still hear "Legal review for the Acme master services agreement". The problem is sighted users, and the quick fix, a title attribute, is weak: it shows only on mouse hover after a delay, never on keyboard focus, and not at all on touch. Use a small tooltip that opens on hover and on focus instead (the tooltip guide covers it), and only when the label is actually cut, which you know from the measurement.

Telling search engines: BreadcrumbList structured data

For public pages (the catalog, the docs), the trail is also a signal to search engines about where the page sits. You describe it with structured data: a small JSON block in the page, using the schema.org BreadcrumbList type. Google's breadcrumb docs accept JSON-LD, RDFa and Microdata; JSON-LD is the easiest to generate because it is separate from the visible markup.

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Electronics",
      "item": "https://shop.example.com/electronics" },
    { "@type": "ListItem", "position": 2, "name": "Laptops",
      "item": "https://shop.example.com/electronics/laptops" },
    { "@type": "ListItem", "position": 3, "name": "ThinkPad X1" }
  ]
}

• What Google requires. At least two ListItems, each with name, position and item (the URL); only the last may leave out item. Google doesn't need a ListItem for the home page, so starting at Electronics is fine even though the visible trail starts at Home.
• One source. Generate the JSON-LD from the same crumb array that renders the nav, on the server. Two hand written copies drift apart within a month.
• Absolute URLs in item, and the canonical ones, so the multi parent product always reports its primary category.
• Real labels only. Never emit a placeholder or an id. If a label didn't resolve on the server, leave the JSON-LD out of that response rather than send "Project".
• Escape it. Names are user data. Serialize with JSON.stringify and replace the less than sign with its unicode escape, or a folder named with a closing script tag breaks out of the block: a real XSS path.
• Logged in pages get none. The Drive trail is private; there is nothing for a crawler to see.

What does Google show? On desktop results, the visible URL above the title can show the domain followed by the breadcrumb trail. On January 23, 2025, Google began rolling out a change that removes breadcrumbs from mobile results, which now show only the domain. Google said sites need to do nothing, since it still supports breadcrumb markup for desktop results.

So structured data is still worth a few lines, but don't sell it as a ranking lever: it describes the page, it doesn't rank it. The Rich Results Test and the Search Console breadcrumb report tell you whether Google parsed it.

Architecture, data model and component API

Put the pieces together. The rule from the derivation chapter shapes everything: the design system component draws, and app code derives. That boundary lets 40 teams with two routers share one component.

Why not fetch labels inside the component? The page already has most of them, and a second fetch path means two caches with two answers for the same name. The component stays a pure function of its props plus its own width.

Data model

// design system: what the component renders
export type Crumb = {
  key: string;            // stable: route id or item id, not the index
  label: string | null;   // null = still loading: render a skeleton
  href?: string;          // absent on the current page
  icon?: "home" | "folder";
};

// app side: an item that knows its parents (from the API)
type FolderWithPath = {
  id: string; name: string;
  ancestors: { id: string; name: string }[]; // root first
};

// app side: the label cache key
type LabelKey = `${"org" | "project" | "folder"}:${string}`;

One correctness trap sits in the cache: renames and moves. Renaming Acme Inc to Acme Corp must update the label entry org:42 and every cached chain that includes it, or the trail shows the old name until the cache expires. Moving a folder changes the chains of everything under it, so invalidate those chains rather than patch them. The google drive guide covers moves and the folder tree in depth.

The component API

The big libraries split two ways. MUI and Carbon take children: you write each link inside the component (Carbon marks the last one with isCurrentPage). Ant Design moved to an items array in version 5.3, with itemRender to draw each item. Which suits a shared component with measured overflow?

type BreadcrumbsProps = {
  items: Crumb[];
  linkAs?: React.ElementType;        // Next Link, React Router Link, or "a"
  maxItems?: number;                 // hard cap even when wide; default 8
  itemsBeforeCollapse?: number;      // minimum kept; default 1 (the root)
  itemsAfterCollapse?: number;       // "rules" mode; default 2 (parent, current)
  collapse?: "measure" | "rules";    // default "measure"
  compactBelow?: number;             // px; back to parent below this, default 320
  currentAsLink?: boolean;           // default false
  separator?: "slash" | "chevron";   // tokens, not any node
  labels?: { nav: string; showMore: (n: number) => string; back: (p: string) => string };
};

<Breadcrumbs items={useTrail()} linkAs={Link}
  labels={{ nav: t("crumbs.nav"), showMore: (n) => t("crumbs.more", { n }),
            back: (p) => t("crumbs.back", { parent: p }) }} />

Why linkAs and not an onNavigate callback? A real anchor with an href keeps Cmd or Ctrl click, middle click, "copy link" and prefetching on hover, which a callback on a button would lose. The router's Link renders that anchor and adds client side navigation on a plain click. The component passes it href, the children and its own class, and nothing else.

• Defaults that are correct. With no props except items, you get the nav, the list, aria-current, measured collapse and a 24 pixel target. Accessibility can't be opted out of by forgetting a prop.
• Separator as a token, not any node. A free node invites text separators that screen readers read aloud; tokens stay aria-hidden and mirror for right to left.
• Every string is a prop with a translated default. The landmark label, "Show 6 more levels" and "Back to Legal review" all need plural rules and word order per language, so they are functions of a count or a name, not fixed strings to concatenate.
• Stable keys. Crumb.key is a route id or item id. Using the index as key makes React reuse the wrong DOM node when a level is inserted, which can move focus to the wrong link.

Correctness and performance: no shifts, no stale trails

A trail is tiny, so performance means two things: it must not move the page (Cumulative Layout Shift, CLS), and it must never be wrong for even one frame after a navigation.

No layout shift

The breadcrumb sits above the h1, so anything that changes its height pushes the whole page down. Google's guidance is a CLS of 0.1 or less at the 75th percentile. If a late 24 pixel row pushes most of an 800 pixel phone screen down, that one shift scores about 0.03 (24 divided by 800): a third of the budget for one row of links.

• One line, always. No wrapping means the height is fixed at the line height plus padding, known before any label loads.
• Fixed width skeletons. A loading label is an 80 pixel bar of text height, not an empty span that grows.
• Server rendered trail. Next.js server layouts or React Router loaders put the real names in the HTML, so there is often nothing to load at all.
• Collapse first, adjust on the same line. The server sends the conservative layout; the client's changes stay on one line, so nothing below moves.

The stale trail bug

A common bug: a Next.js layout renders the breadcrumb and keeps its state across navigations, because layouts don't remount. The user goes from folder Contracts to folder Invoices. The URL changes at once, but the new folder's ancestors are still loading, so for 300 ms the trail shows Invoices' URL with Contracts' parents. Worse, if the Contracts request finishes late, it can overwrite the new trail.

• Key the trail data by the current item id, never "the last response". The server state cache does this for free: the query key includes the folder id.
• Derive the static part from the current matches on every render; don't copy it into state.
• While the new chain loads, show the new static frame and skeletons, not the old chain. An old name next to a new URL is worse than a placeholder.
• Abort or ignore responses for ids that are no longer current (the request races lesson covers the pattern).

Long file paths, GitHub style

A code browser's trail is a file path: repo / src / components / system-design / extras / GuideTabs.tsx. Developers want two things there that a catalog doesn't need. First, every directory is a link, and the path is often long, so measured collapse matters even on desktop. Second, they want the path as text, which is why GitHub puts a Copy path button next to its file path.

Add it as an optional action outside the ol: a real button whose click calls navigator.clipboard.writeText with the joined path, then shows "Copied" and announces it through a polite live region. The clipboard API works only in a secure context (HTTPS), and some browsers also require a user gesture, which the click provides.

Running it in the interview

Breadcrumbs is a 30 minute question, and the trap is finishing the markup in 5 minutes and then having nothing to say. Spend the time on the parts that show judgment.

Say your trade-offs out loud. "I'll measure instead of using maxItems because labels are user data" earns more than the measurement code itself. Expect these follow-ups: