XDS — Design System

XDSBreadcrumbItem@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 {XDSBreadcrumbItem} from '@xds/core/Breadcrumbs'

Props

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.

Showcase source

tsx
'use client';
import type {ComponentProps} from 'react';
import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
function HomeIcon(props: ComponentProps<'svg'>) {
  return (
    <svg
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={2}
      stroke="currentColor"
      {...props}>
      <path
        strokeLinecap="round"
        strokeLinejoin="round"
        d="M3 9.5L12 3l9 6.5V20a1 1 0 01-1 1H4a1 1 0 01-1-1V9.5z"
      />
    </svg>
  );
}
export default function BreadcrumbItemShowcase() {
  return (
    <XDSVStack gap={4}>
      <XDSVStack gap={1}>
        <XDSText type="supporting" color="secondary">
          With start icon
        </XDSText>
        <XDSBreadcrumbs>
          <XDSBreadcrumbItem href="/" startIcon={<HomeIcon />}>
            Home
          </XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/docs">Docs</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>Components</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSVStack>
      <XDSVStack gap={1}>
        <XDSText type="supporting" color="secondary">
          As current page (non-link)
        </XDSText>
        <XDSBreadcrumbs>
          <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/settings">Settings</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>Profile</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSVStack>
      <XDSVStack gap={1}>
        <XDSText type="supporting" color="secondary">
          Supporting variant
        </XDSText>
        <XDSBreadcrumbs variant="supporting">
          <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/admin">Admin</XDSBreadcrumbItem>
          <XDSBreadcrumbItem href="/admin/users">Users</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>Permissions</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSVStack>
      <XDSVStack gap={1}>
        <XDSText type="supporting" color="secondary">
          With onClick handler (no href)
        </XDSText>
        <XDSBreadcrumbs>
          <XDSBreadcrumbItem onClick={() => {}}>Dashboard</XDSBreadcrumbItem>
          <XDSBreadcrumbItem onClick={() => {}}>Projects</XDSBreadcrumbItem>
          <XDSBreadcrumbItem isCurrent>Project Alpha</XDSBreadcrumbItem>
        </XDSBreadcrumbs>
      </XDSVStack>
    </XDSVStack>
  );
}