XDS — Design System

Breadcrumbs@xds/core v0.0.13 · 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.

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 — Separators

Swap the default

Breadcrumbs — Deep Path

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

Breadcrumbs — Variants

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

Breadcrumbs — Icons

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

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={{}}.