Breadcrumbs

Choose a location path #

Use breadcrumbs when users benefit from understanding the current location in a meaningful hierarchy and returning to ancestors. They supplement primary navigation. A browsing-history trail, sequential task steps and an arbitrary list of related pages are different models.

The application supplies the path from its actual information architecture. URL segments alone do not prove hierarchy. This guide uses an explicitly authored documentation path from system home through navigation guidance to this component.

• Give ancestors real href values; preserve native open-in-new-tab/history behavior.
• Use BreadcrumbPage for current non-link text, or an actual current link with aria-current when appropriate. Avoid multiple current locations in one path.
• Keep the path short enough to understand. If collapsing ancestors, provide an accessible way to recover them; decorative ellipsis alone is not recovery.

Anatomy, layout and states #

Working ancestry destinations #

'use client';
import { useState } from 'react';
import { BreadcrumbLink, BreadcrumbPage, Breadcrumbs, Button } from '@mobtranslate/ui';

export function BreadcrumbNavigationExample() {
  const [rtl, setRtl] = useState(false);
  const [custom, setCustom] = useState(false);
  const [long, setLong] = useState(false);
  return <div data-breadcrumb-lab className="space-y-4">
    <div className="flex flex-wrap gap-3"><Button type="button" variant="outline" aria-pressed={rtl} onClick={() => setRtl(current => !current)}>Use RTL local breadcrumbs</Button><Button type="button" variant="outline" aria-pressed={custom} onClick={() => setCustom(current => !current)}>Use slash breadcrumb separator</Button><Button type="button" variant="outline" aria-pressed={long} onClick={() => setLong(current => !current)}>Use long breadcrumb labels</Button></div>
    <div dir={rtl ? 'rtl' : 'ltr'}><Breadcrumbs aria-label="Navigation documentation path" separator={custom ? '/' : undefined}>
      <BreadcrumbLink href="/">{long ? 'MobTranslate design system and implementation guidance home' : 'Design system home'}</BreadcrumbLink>
      <BreadcrumbLink href="/patterns/navigation">{long ? 'Navigation and related task-view patterns' : 'Navigation patterns'}</BreadcrumbLink>
      <BreadcrumbPage>Breadcrumbs</BreadcrumbPage>
    </Breadcrumbs></div>
    <p>This authored documentation path uses real ancestors and the current guide. It is independent of browsing history and does not grant source access or authority.</p>
  </div>;
}

API reference #

Keyboard, route state and recovery #

• Tab visits ancestor links; Enter follows their actual href. Current text and decorative separators remain outside the Tab order. No arrow-key composite or history inference is implemented.
• Native links can be copied or opened elsewhere. A router integration must preserve those semantics, actual URL/current-location state, arrival focus and back/forward behavior.
• A path becoming stale after moved/deleted content needs a deliberate canonical ancestor or recovery link, not a made-up parent. Do not silently discard source provenance while renaming visible labels.
• Long names wrap with full text. A compact collapsed variant needs a working expand/menu control, naming and focus recovery; that behavior is not supplied by separator alone.
• Source restrictions and permission remain independent. A breadcrumb path only states location within the application.

Common failures #

• Do not use href="#" placeholders for ancestors or announce related destinations as parentage without an authored hierarchy.
• Do not put interactive content inside aria-hidden separators; it can still receive keyboard focus.
• Do not apply button border/hover treatment to list-item containers. Link/current styles target the actual emitted classes.
• Custom separator text should be hidden from screen-reader path narration while full location names remain available. Test a named assistive-technology/browser pair before claiming spoken results.

Verification and release scope #

• Follow actual destinations and read actual records. Check native link/button semantics, names, current state, focus, unavailable activation and retained versus requested outcomes. Appearance or callbacks alone are insufficient.
• Test both themes, long labels, 320px reflow, RTL/orientation, zoom/text spacing, reduced motion and forced colors. Device touch and spoken announcements need named platform evidence.
• Run test:destinations, checked-source/token freshness, lint, UI/styleguide typechecks, production build and route/fragment crawl. The suite supplies scoped browser evidence, not whole-library certification.
• The English-only local fixture establishes no source quality, cultural authority, permission, authenticated access, persistent write or remote collection result.

Related guidance #