breadcrumb-core 🧭

Zero-config breadcrumbs from your route config — progressive loading, custom matchers, i18n, collapsible overflow, SEO JSON-LD, and adapters for React Router, Next.js, and TanStack Router.

🌐 Live Demo · npm · GitHub · Changelog

Installation

npm install breadcrumb-core

Quick Start

// main.tsx / app/layout.tsx
import { BreadcrumbProvider } from 'breadcrumb-core/react-router' // or /next, /tanstack-router
import { routes } from './routes'

<BreadcrumbProvider routes={routes}>
  <App />
</BreadcrumbProvider>

// Any page — zero breadcrumb code
import { AutoBreadcrumb } from 'breadcrumb-core/react-router'
<AutoBreadcrumb separator="/" injectJsonLd syncDocumentTitle appName="MyApp" />
// → Home / Products / iPhone 15 / Reviews

Route Config (v3)

import type { RouteConfig } from 'breadcrumb-core'

const routes: RouteConfig[] = [
  { path: '/', label: 'Home' },

  // Standard named param
  { path: '/products', label: 'Products' },
  { path: '/products/:id', label: async ({ params }) => fetchName(params.id), cacheTtl: 60_000 },

  // Wildcard
  { path: '/docs/*', label: 'Docs' },

  // Optional param
  { path: '/shop/:category?', label: ({ params }) => params.category ?? 'All' },

  // RegExp matcher with named groups (v3)
  { path: /^\/p\/(?<id>\d+)$/, label: ({ params }) => `Product ${params.id}` },

  // Function matcher (v3)
  {
    path: (pathname) => {
      const m = pathname.match(/^\/items-(\w+)$/)
      return m ? { slug: m[1] } : null
    },
    label: ({ params }) => `Item: ${params.slug}`,
  },

  // With icon, hidden, onMatch
  { path: '/settings', label: 'Settings', icon: <GearIcon />, onMatch: ({ pathname }) => analytics.page(pathname) },
  { path: '/app', label: 'App', hidden: true },
]

v3 Features

Progressive per-item loading (v3)

Static labels render instantly. Async labels each show a skeleton independently and swap in as they resolve:

// Default behaviour — nothing to change
<AutoBreadcrumb />

// Custom per-item skeleton
<AutoBreadcrumb
  renderItemSkeleton={(item) => (
    <span className="my-skeleton" style={{ width: item.isLast ? 100 : 60 }} />
  )}
/>

i18n locale-prefix stripping (v3)

// Handles /en/products/42 and /fr/products/42 with the same route definitions
<BreadcrumbProvider routes={routes} locales={['en', 'fr', 'de', 'ja']}>

// Read detected locale anywhere
import { useBreadcrumbLocale } from 'breadcrumb-core/react-router'
const locale = useBreadcrumbLocale() // → 'fr'

Label transform (v3)

// Post-process every label globally
<BreadcrumbProvider
  routes={routes}
  transformLabel={(label) => t(label)} // e.g. i18next
/>

Collapsible overflow (v3)

import { CollapsibleBreadcrumb } from 'breadcrumb-core/ui'

// Home / ••• / Reviews  — click ••• to expand inline
<CollapsibleBreadcrumb collapseAt={4} theme="light" />

Active route hook (v3)

import { useActiveRoute } from 'breadcrumb-core/react-router'
const active = useActiveRoute()
// → { path, label, params, isLast, route } | null

Cache invalidation after mutations

import { invalidateLabelCache } from 'breadcrumb-core'
await renameProduct(id, newName)
invalidateLabelCache(productRoute, { id })

Analytics

<BreadcrumbProvider
  routes={routes}
  onNavigate={(items, pathname) =>
    analytics.page(pathname, { trail: items.map(i => i.label).join(' > ') })
  }
/>

API Reference

<BreadcrumbProvider>

| Prop | Type | Default | Description | |------|------|---------|-------------| | routes | RouteConfig[] | required | Route definitions | | children | ReactNode | required | App content | | onNavigate | (items, pathname) => void | — | Called after each navigation | | maxHistory | number | 20 | Max snapshots for useBreadcrumbHistory() | | locales | string[] | — | v3 i18n locale prefixes to strip | | transformLabel | (label, item) => string | — | v3 Global label transformer |

<AutoBreadcrumb>

| Prop | Type | Default | Description | |------|------|---------|-------------| | separator | ReactNode | "/" | Between items | | maxItems | number | — | Collapse middle with … (static) | | showHome | boolean | true | Include root item | | className | string | — | CSS class on <nav> | | syncDocumentTitle | boolean | false | Auto-update document.title | | appName | string | — | Appended to synced title | | injectJsonLd | boolean | false | Inject Schema.org JSON-LD | | baseUrl | string | "" | Base URL for JSON-LD | | renderItem | (item, isLast) => ReactNode | — | Custom item renderer | | renderItemSkeleton | (item) => ReactNode | — | v3 Per-item skeleton | | renderSkeleton | () => ReactNode | — | Full-replacement skeleton (legacy) | | progressiveLoading | boolean | true | v3 Per-item async rendering | | ariaLabel | string | "breadcrumb" | aria-label on <nav> | | onItemClick | (item) => boolean \| void | — | Intercept item clicks |

RouteConfig

| Field | Type | Description | |-------|------|-------------| | path | string \| RegExp \| fn | v3 string, RegExp with groups, or (pathname) => params \| null | | label | string \| fn | Static or async. fn receives { params, pathname } | | icon | ReactNode | Icon before label | | hidden | boolean | Skip in breadcrumb | | cacheTtl | number | Cache TTL in ms | | onMatch | fn | Called when segment is matched |

Hooks

| Hook | Returns | Description | |------|---------|-------------| | useBreadcrumb() | BreadcrumbItem[] | Current items (with isLoading per item) | | useBreadcrumbLoading() | boolean | True while any label is resolving | | useBreadcrumbHistory() | BreadcrumbItem[][] | Navigation snapshots | | useActiveRoute() | BreadcrumbItem \| null | v3 Last (current) item | | useBreadcrumbLocale() | string \| null | v3 Detected locale prefix |

Core utilities

import {
  matchRoute,
  buildBreadcrumbs,
  buildBreadcrumbsProgressive, // v3
  generateJsonLd,
  clearLabelCache,
  invalidateLabelCache,
  stripLocalePrefix,            // v3
  withLocalePrefix,             // v3
} from 'breadcrumb-core'

UI components

import {
  StyledBreadcrumb,        // themes: light | dark | minimal | pill
  CollapsibleBreadcrumb,   // v3: expandable ••• overflow
  BreadcrumbSkeleton,      // full-row shimmer
} from 'breadcrumb-core/ui'

Migration

• v1 → v3: No breaking changes. Drop in v3 and get progressive loading automatically.
• v2 → v3: No breaking changes. All v2 features still work unchanged.
• See CHANGELOG.md for the full additions per version.

License

MIT © virendra2902