Breadcrumbs

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

BreadcrumbItem represents one destination, action, current location, or sibling-menu trigger inside a Breadcrumbs trail.

Prop	Type	Description
children *	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	Marks this item as the current page, applying aria-current="page". When omitted, the last item is auto-detected if no item is explicitly current; pass false to opt out.
startIcon	ReactNode	Icon rendered before the item label.
menu	DropdownMenuOption[] \| ReactNode	Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.
menuSize	'sm' \| 'md' \| 'lg'	Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').
as	LinkComponentType	Custom link component to render instead of <a>. Overrides the provider-level default from LinkProvider. Only applies to non-current items.

Breadcrumbs

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.

Prop	Type	Default	Description
children *	ReactNode		BreadcrumbItem elements to render inside the breadcrumb trail.
separator	ReactNode	'/'	Separator rendered between breadcrumb items. The built-in slash mirrors automatically in RTL.
variant	'default' \| 'supporting'	'default'	Visual variant: supporting is smaller with secondary text styling.
label	string	'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={{}}.

Usage guidance

Place breadcrumbs above the page heading so the user sees their location before reading the content.
Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".
Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.
Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.
The component implements the WAI-ARIA APG Breadcrumb pattern: a labelled nav landmark wrapping an ordered list, with aria-current="page" on the current item. A crumb with a menu additionally implements the APG Menu Button pattern, opening on Enter, Space or ArrowDown and closing on Escape.
Give each trail its own label when a page renders more than one, so the nav landmarks stay distinguishable in a screen reader landmark list.
Avoid: Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.
Avoid: Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.
Avoid: Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.
The built-in slash separator mirrors automatically in RTL. For a custom separator, leave Unicode-mirrored angle quotes such as › alone; mirror arrows and Icon separators once with rtlStyles.mirror.
Avoid: Mirror a separator the bidi algorithm already mirrors. An angle-quote glyph such as › is Bidi_Mirrored, so it flips under RTL on its own and rtlStyles.mirror would flip it back. An arrow glyph such as → and any Icon separator are not, so those do need rtlStyles.mirror through xstyle.

Theming API

{
  "targets": [
    {
      "className": "astryx-breadcrumb-item",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-breadcrumb-item-menu-trigger",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-breadcrumb-menu"
    },
    {
      "className": "astryx-breadcrumbs",
      "visualProps": [
        "variant"
      ]
    }
  ]
}

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

Prop	Type	Description
children *	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	Marks this item as the current page, applying aria-current="page". When omitted, the last item is auto-detected if no item is explicitly current; pass false to opt out.
startIcon	ReactNode	Icon rendered before the item label.
as	LinkComponentType	Custom link component to render instead of <a>. Overrides the provider-level default from LinkProvider. Only applies to non-current items.
menu	DropdownMenuOption[] \| ReactNode	Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.
menuSize	'sm' \| 'md' \| 'lg'	Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').

Anatomy

Trail: The ordered list of links from root to current page.
Item: A single step in the trail. Renders as a link or plain text for the current page.
Separator: 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.

Examples

Breadcrumb Item: BreadcrumbItem represents a single step in a breadcrumb trail, supporting links, icons, current-page markers, and custom link components.
Breadcrumbs: A breadcrumb trail showing page hierarchy with linked ancestors and a current page.
BreadcrumbItem — Basic: Breadcrumb links inside a Breadcrumbs trail. Ancestor pages get an href; mark the last item with isCurrent to render it as plain text for the current page.
Breadcrumbs — Separators: Swap the default "/" for a different character like chevrons, arrows, or dots. Use when the visual style of the page calls for a different separator.
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 — Menu item: Give a mid-trail crumb a menu prop to turn it into a menu trigger for switching between sibling destinations. It reuses the same item API as DropdownMenu, so an existing option array (or composed item children) drops in verbatim.
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.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0

Breadcrumbs

Breadcrumbs

Installation

Breadcrumb Item

Breadcrumbs

Usage guidance

Theming API

Breadcrumb Item

Anatomy

Examples

Complete example dependencies