XDS — Design System

XDSBreadcrumbs@xds/core · Breadcrumbs

Usage

Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.

Best practices

Guidance	Practices
Do	Place breadcrumbs above the page heading so the user sees their location before reading the content.
Do	Keep labels short and match the page titles they link to — "Settings" not "Application Settings Page".
Do	Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.
Do	Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent.
Don't	Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it.
Don't	Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user.
Don't	Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead.

Anatomy

Element		Description
Trail	required	The ordered list of links from root to current page.
Item	required	A single step in the trail. Renders as a link or plain text for the current page.
Separator	required	The character between items. Defaults to "/" but can be customized.
Icon		An optional icon before an item label, like a home icon on the first item.

Import

ts
import {XDSBreadcrumbs} from '@xds/core/Breadcrumbs'

Props

Prop	Type	Description
childrenrequired	ReactNode	XDSBreadcrumbItem elements to render inside the breadcrumb trail.
separator	ReactNode (default: '/')	Separator rendered between breadcrumb items.
variant	'default' \| 'supporting' (default: 'default')	Visual variant — supporting is smaller with secondary text styling.
label	string (default: 'Breadcrumb')	Accessible label for the nav landmark (aria-label).
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Sub-components

Breadcrumbs is a compound component with 2 sub-components.

XDSBreadcrumbItem

Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.

Prop	Type	Description
childrenrequired	ReactNode	Label content for the breadcrumb item.
href	string	URL the breadcrumb links to; omit for non-navigable items.
onClick	(e: MouseEvent) => void	Click handler for the breadcrumb item.
isCurrent	boolean (default: false)	Marks this item as the current page, applying aria-current="page".
startIcon	ReactNode	Icon rendered before the item label.
as	XDSLinkComponentType	Custom link component to render instead of <a>. Overrides the provider-level default from XDSLinkProvider. Only applies to non-current items.

XDSBreadcrumbs

Navigation container that renders a <nav> with an ordered list of breadcrumb items.

Prop	Type	Description
childrenrequired	ReactNode	XDSBreadcrumbItem elements to render inside the breadcrumb trail.
separator	ReactNode (default: '/')	Separator rendered between breadcrumb items.
variant	'default' \| 'supporting' (default: 'default')	Visual variant — supporting is smaller with secondary text styling.
label	string (default: 'Breadcrumb')	Accessible label for the nav landmark (aria-label).
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Examples

Common configurations, variations, and states.

Breadcrumbs — Deep PathA 5-level breadcrumb trail for deeply nested content. Use in e-commerce, file browsers, or any UI with several levels of hierarchy.

tsx
'use client';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
import {XDSIcon} from '@xds/core/Icon';
import {HomeIcon} from '@heroicons/react/24/outline';
export default function BreadcrumbsDeepHierarchy() {
  return (
    <XDSBreadcrumbs>
      <XDSBreadcrumbItem
        href="/"
        startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>
        Home
      </XDSBreadcrumbItem>
      <XDSBreadcrumbItem href="/products">Products</XDSBreadcrumbItem>
      <XDSBreadcrumbItem href="/products/electronics">
        Electronics
      </XDSBreadcrumbItem>
      <XDSBreadcrumbItem href="/products/electronics/phones">
        Phones
      </XDSBreadcrumbItem>
      <XDSBreadcrumbItem isCurrent>iPhone 15 Pro</XDSBreadcrumbItem>
    </XDSBreadcrumbs>
  );
}

Breadcrumbs — IconsAdd icons before breadcrumb labels for quick recognition. Use a home icon on the root item and contextual icons on key sections.

tsx
'use client';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
import {XDSIcon} from '@xds/core/Icon';
import {HomeIcon, Cog6ToothIcon} from '@heroicons/react/24/outline';
export default function BreadcrumbsWithIcons() {
  return (
    <XDSBreadcrumbs>
      <XDSBreadcrumbItem
        href="/"
        startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>
        Home
      </XDSBreadcrumbItem>
      <XDSBreadcrumbItem
        href="/settings"
        startIcon={<XDSIcon icon={Cog6ToothIcon} size="sm" />}>
        Settings
      </XDSBreadcrumbItem>
      <XDSBreadcrumbItem isCurrent>Profile</XDSBreadcrumbItem>
    </XDSBreadcrumbs>
  );
}

Breadcrumbs — SeparatorsSwap the default

tsx
'use client';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
const SEPARATORS = [
  {char: '›', label: 'Chevron'},
  {char: '→', label: 'Arrow'},
  {char: '·', label: 'Dot'},
];
export default function BreadcrumbsCustomSeparator() {
  return (
    <XDSStack direction="vertical" gap={4}>
      {SEPARATORS.map(({char, label}) => (
        <XDSStack key={label} direction="vertical" gap={1}>
          <XDSText type="supporting" color="secondary">
            {label}
          </XDSText>
          <XDSBreadcrumbs separator={char}>
            <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
            <XDSBreadcrumbItem href="/docs">Docs</XDSBreadcrumbItem>
            <XDSBreadcrumbItem isCurrent>API Reference</XDSBreadcrumbItem>
          </XDSBreadcrumbs>
        </XDSStack>
      ))}
    </XDSStack>
  );
}

Breadcrumbs — VariantsCompare the default and supporting variants side by side. Use the supporting variant in dense UIs like admin panels where the breadcrumb should be subtle.

tsx
'use client';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function BreadcrumbsSupportingVariant() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Default
        </XDSText>
        <XDSBreadcrumbs>
          <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Supporting
        </XDSText>
        <XDSBreadcrumbs variant="supporting">
          <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSStack>
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
export default function BreadcrumbsShowcase() {
  return (
    <XDSBreadcrumbs>
      <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
      <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
      <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
    </XDSBreadcrumbs>
  );
}