Breadcrumbs

A navigation component that displays the current page's location within the application hierarchy. Built on MUI Breadcrumbs with support for nested navigation, custom separators, router integration, and automatic path resolution from tree structures. Ideal for multi-level dashboards, content hierarchies, and complex navigation flows.

Quick Start

Copy & Paste

import { Breadcrumbs } from '@dashforge/ui';

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'products', label: 'Products', href: '/products' },
  { id: 'details', label: 'Product Details' }
];

<Breadcrumbs pathname="/products/details" items={items} />

Examples

Common Breadcrumbs patterns and configurations

Basic Breadcrumbs

Simple navigation path with clickable links

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'dashboard', label: 'Dashboard' }
];

<Breadcrumbs pathname="/dashboard" items={items} />

Nested Navigation

Multi-level hierarchy with 4 levels

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'products', label: 'Products', href: '/products' },
  { id: 'category', label: 'Electronics', href: '/products/electronics' },
  { id: 'product', label: 'Laptop' }
];

<Breadcrumbs pathname="/products/electronics/laptop" items={items} />

Custom Separator

Breadcrumbs with chevron icon separator

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'settings', label: 'Settings', href: '/settings' },
  { id: 'account', label: 'Account' }
];

<Breadcrumbs 
  pathname="/settings/account" 
  items={items}
  separator={<ChevronRightIcon fontSize="small" />}
/>

With Icons

Home icon in first breadcrumb item

const items = [
  { id: 'home', label: <HomeIcon fontSize="small" />, href: '/' },
  { id: 'blog', label: 'Blog', href: '/blog' },
  { id: 'article', label: 'Getting Started' }
];

<Breadcrumbs pathname="/blog/getting-started" items={items} />

Disabled Items

Non-clickable breadcrumb items

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'reports', label: 'Reports', href: '/reports', disabled: true },
  { id: 'analytics', label: 'Analytics' }
];

<Breadcrumbs pathname="/reports/analytics" items={items} />

Max Items

Collapsed breadcrumbs with ellipsis

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'level1', label: 'Level 1', href: '/level1' },
  { id: 'level2', label: 'Level 2', href: '/level1/level2' },
  { id: 'level3', label: 'Level 3', href: '/level1/level2/level3' },
  { id: 'level4', label: 'Level 4' }
];

<Breadcrumbs 
  pathname="/level1/level2/level3/level4" 
  items={items}
  maxItems={3}
/>

Dashforge Capabilities

Flexible navigation with router integration and automatic path resolution

Breadcrumbs provides flexible navigation with router integration, automatic path resolution from tree structures, and extensive customization options for labels, separators, and rendering.

Flexible Structure

Navigation

Use controlled items array or automatic tree resolution. Supports nested hierarchies with custom matching logic.

Controlled or tree-based

Automatic path resolution

Nested hierarchy support

const items = [
  { id: 'home', label: 'Home', href: '/' },
  { id: 'page', label: 'Current Page' }
];

<Breadcrumbs pathname="/page" items={items} />

Router Integration

Framework Agnostic

Works with any router. Pass custom LinkComponent for React Router or Next.js Link integration.

Custom link components

Framework agnostic design

getLinkProps for customization

import { Link } from 'react-router-dom';

<Breadcrumbs 
  pathname="/page"
  items={items}
  LinkComponent={Link}
  getLinkProps={(node) => ({ to: node.href })}
/>

Custom Rendering

Flexible

Customize labels with React nodes or i18n hooks. Control separators, icons, and styling via props.

Custom separators and icons

getLabel for i18n

slotProps for styling

<Breadcrumbs 
  pathname="/page"
  items={items}
  separator={<ChevronRightIcon />}
  getLabel={(node) => t(node.label)}
  slotProps={{ link: { sx: { color: 'primary.main' } } }}
/>

Navigation Scenarios

Real-world navigation patterns with dynamic paths and nested hierarchies

Automatic Path Resolution

Define a navigation tree once and let Breadcrumbs automatically resolve the path hierarchy. Perfect for dashboard layouts where the structure is known but the current page changes dynamically.

Interactive Demo

Navigate to:

Current pathname:

/dashboard/analytics/reports

const tree = [
  {
    id: 'dashboard',
    label: 'Dashboard',
    href: '/dashboard',
    children: [
      {
        id: 'analytics',
        label: 'Analytics',
        href: '/dashboard/analytics',
        children: [
          { id: 'reports', label: 'Reports', href: '/dashboard/analytics/reports' },
          { id: 'insights', label: 'Insights', href: '/dashboard/analytics/insights' }
        ]
      },
      {
        id: 'settings',
        label: 'Settings',
        href: '/dashboard/settings',
        children: [
          { id: 'account', label: 'Account', href: '/dashboard/settings/account' }
        ]
      }
    ]
  }
];

<Breadcrumbs pathname={currentPath} tree={tree} />

Why it matters

Tree-based resolution eliminates the need to manually construct breadcrumb arrays on every page. Define your navigation structure once (often from your router config), and breadcrumbs resolve automatically based on the current pathname.

Custom Separators & Icons

Customize breadcrumb appearance with custom separators, icons, and label rendering. Supports React nodes for full flexibility.

Interactive Demo

Separator

Home Display

Current configuration:

• Separator: slash

• Home display: text

import HomeIcon from '@mui/icons-material/Home';
import ChevronRightIcon from '@mui/icons-material/ChevronRight';

const items = [
  { id: 'home', label: <HomeIcon fontSize="small" />, href: '/' },
  { id: 'products', label: 'Products', href: '/products' },
  { id: 'category', label: 'Electronics', href: '/products/electronics' },
  { id: 'product', label: 'Laptop' }
];

<Breadcrumbs 
  pathname="/products/electronics/laptop"
  items={items}
  separator={<ChevronRightIcon fontSize="small" />}
/>

Why it matters

Custom rendering allows you to match your brand's design system. Replace text with icons, use custom separators, or integrate i18n via the getLabel prop. The component stays flexible without requiring component extension.

API Reference

Complete props and type definitions

Prop	Type	Default	Description
pathname	string	-	Current pathname used to determine the active breadcrumb item (router-agnostic)
items	BreadcrumbNode[]	-	Controlled mode: explicitly provide breadcrumb items. Last item is treated as active.
tree	BreadcrumbNode[]	-	Uncontrolled mode: provide navigation tree structure. Component automatically resolves breadcrumb chain from pathname.
home	BreadcrumbNode	-	Home breadcrumb node prepended when includeHome is true and active item is not home
includeHome	boolean	-	Whether to automatically prepend home breadcrumb when not at root
LinkComponent	React.ElementType	-	Custom link component for router integration (e.g., React Router Link, Next.js Link)
getLinkProps	(node: BreadcrumbNode) => LinkProps	-	Function to customize props passed to LinkComponent (e.g., convert href to "to" for React Router)
getLabel	(node: BreadcrumbNode) => React.ReactNode	-	Label resolver function for i18n or custom rendering. If omitted, uses node.label directly.
separator	React.ReactNode	-	Separator displayed between breadcrumb items (can be text, icon, or any React node)
maxItems	number	-	Maximum number of breadcrumbs to display. Middle items are collapsed with ellipsis.
sx	SxProps<Theme>	-	MUI system style overrides for the root Breadcrumbs
slotProps	object	-	Fine-grained styling overrides: { link?: { sx }, active?: { sx } }

Type Definitions

BreadcrumbNode

{
  id: string;
  label: string | React.ReactNode;
  href?: string;
  match?: 'exact' | 'prefix';
  disabled?: boolean;
  children?: BreadcrumbNode[];
  meta?: unknown;
}

Implementation Notes

Technical details and best practices

Built on MUI Breadcrumbs

Breadcrumbs is built on top of MUI Breadcrumbs component, inheriting its accessibility features (aria-current, aria-label) and responsive behavior. The component wraps MUI with intelligent path resolution and router integration.

Two Usage Modes

Use controlled mode (items prop) for simple, explicit breadcrumb chains. Use tree mode (tree prop) for automatic path resolution from navigation hierarchies. Tree mode is ideal when your navigation structure matches your breadcrumb needs.

Pathname is Router-Agnostic

The pathname prop accepts a plain string, making the component work with any router (React Router, Next.js, or custom). No router-specific dependencies required. Simply pass location.pathname or usePathname() value.

Router Integration

Pass LinkComponent prop to integrate with your router. For React Router, use Link component. For Next.js, use Next Link. Use getLinkProps to transform href to router-specific props (e.g., href → to for React Router).

Active Item Handling

The last item in the breadcrumb chain is automatically treated as the active (current) page. It renders as non-clickable text with aria-current="page" for accessibility. All preceding items render as clickable links.

Tree Resolution Algorithm

When using tree mode, the component traverses the tree structure to find nodes matching the current pathname. Supports both exact and prefix matching (default). Home breadcrumb is automatically prepended unless disabled via includeHome.

Custom Label Rendering

Labels can be strings or React nodes. Use React nodes for icons (e.g., <HomeIcon />). Use getLabel prop for i18n translation or dynamic rendering. The function receives the node and returns the rendered label.

Separator Customization

Separator accepts any React node: strings ("/", "→", "•"), icons (<ChevronRightIcon />), or custom elements. Separator is rendered between items (not before first or after last item).

Disabled Items

Set disabled: true on a node to render it as non-clickable text even if href is present. Useful for breadcrumbs in locked or restricted navigation paths where you want to show structure but prevent navigation.

Max Items & Ellipsis

Use maxItems prop to collapse long breadcrumb chains. Middle items are replaced with ellipsis (…) while keeping first, last, and ellipsis button visible. This is a built-in MUI Breadcrumbs feature passed through the component.

Styling via slotProps

Use slotProps to customize link and active item styles independently. Example: slotProps={{ link: { sx: { color: "primary.main" } }, active: { sx: { fontWeight: 700 } } }}. Root styles are controlled via sx prop.

Accessibility Built-In

Component includes proper ARIA attributes: aria-label="breadcrumb" on root, aria-current="page" on active item. Focus ring styles are applied via :focus-visible for keyboard navigation. Works with screen readers out of the box.

Breadcrumbs

Examples

Basic Breadcrumbs

Nested Navigation

Custom Separator

With Icons

Disabled Items

Max Items

Dashforge Capabilities

Flexible Structure

Router Integration

Custom Rendering

Navigation Scenarios

Automatic Path Resolution

Custom Separators & Icons

API Reference

Implementation Notes

Built on MUI Breadcrumbs

Two Usage Modes

Pathname is Router-Agnostic

Router Integration

Active Item Handling

Tree Resolution Algorithm

Custom Label Rendering

Separator Customization

Disabled Items

Max Items & Ellipsis

Styling via slotProps

Accessibility Built-In

Related Topics

On This Page