XDS — Design System

Breadcrumbs@xds/core · XDSBreadcrumbs v0.0.13

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.

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

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.

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>
  );
}

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.

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

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.

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.

XDSLinkComponentType

Custom link component to render instead of <a>. Overrides the provider-level default from XDSLinkProvider. Only applies to non-current 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={{}}.

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> ); }

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> ); }

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> ); }

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> ); }

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> ); }