Breadcrumbs

A breadcrumb trail showing a page's location within a hierarchy. Renders a <nav aria-label="Breadcrumb"> with an ordered list, a default chevron separator, and three size variants.

Breadcrumbs show the user's location within a hierarchy and provide a path back to higher levels. Each item is a link to its level, separated by a divider, with the last item marking the current page.

When to use

• To show where the user is within a nested site or app structure
• To give a quick way back to parent levels in deep hierarchies

When not to use

• For flat structures with no real hierarchy
• As primary or main navigation

Content guidelines

• Keep each crumb short and match it to the page or level it represents.
• The last item is the current page and is not a link.
• When the path is long (4+), collapse the middle items into "…" rather than wrapping.
• Use a single, consistent separator between items.

Behaviour guidelines

Item Count sets how many levels are shown; every item except the last links to its level, and the last is the current, non-interactive page.

4+ — middle items collapse into a "…" that can reveal the hidden levels.

Truncate overly long labels rather than letting the trail wrap or push layout.

Accessibility

Expose the breadcrumbs as a navigation landmark with an accessible name (e.g. "Breadcrumb").

Mark the current page with aria-current="page".

Treat separators as decorative so they aren't announced as content.

If the path is collapsed, make the "…" control keyboard-accessible and clearly labelled.

Installation

npm install @xsolla/xui-breadcrumbs

Imports

import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
import type { BreadcrumbItem } from '@xsolla/xui-breadcrumbs';

Quick start

import * as React from 'react';
import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';

export default function Example() {
  return (
    <Breadcrumbs
      items={[
        { label: 'Home', href: '/' },
        { label: 'Products', href: '/products' },
        { label: 'Category', href: '/products/category' },
        { label: 'Current Page' },
      ]}
    />
  );
}

API Reference

<Breadcrumbs>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | items | BreadcrumbItem[] | - | Trail items, ordered root-to-current. Required. | | size | 'sm' \| 'md' \| 'lg' | 'md' | Font / icon size preset (12/14/16px text). | | stretched | boolean | false | Centre the trail and stretch the container to full width. | | separator | ReactNode | chevron icon | Custom separator placed between items (rendered aria-hidden). | | backgroundColor | string | - | Container background colour. | | testID | string | - | Test identifier. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

BreadcrumbItem

| Field | Type | Description | | --- | --- | --- | | label | string | Display text. Required. | | href | string | Link target. Ignored when the item is the last in items (the active item never renders a hyperlink). | | onClick | () => void | Click handler. Not invoked when the item is active or disabled. When href is also provided, preventDefault() is called before invoking — browser navigation is suppressed, so handle navigation yourself. | | disabled | boolean | Reduces opacity, removes tab stop, and prevents interaction. |

Active-item behaviour

The last item in items is treated as the current page. It renders without an href or click handler, gets aria-current="page", and is excluded from the tab order regardless of any href/onClick you pass.

Visually, the active item is distinguished by content colour only — it uses content.primary while the rest of the trail uses content.tertiary. Its font weight stays at 400, the same as every other crumb; the active item is never rendered bolder. This matches the Figma .breadcrumbs-item spec, where all four State variants (Default, Hover, Active, Disable) are weight 400.

Examples

Sizes

import * as React from 'react';
import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';

const items = [
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Details' },
];

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Breadcrumbs size="sm" items={items} />
      <Breadcrumbs size="md" items={items} />
      <Breadcrumbs size="lg" items={items} />
    </div>
  );
}

Custom separator

import * as React from 'react';
import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';

export default function Example() {
  return (
    <Breadcrumbs
      separator={<span style={{ margin: '0 8px' }}>/</span>}
      items={[
        { label: 'Home', href: '/' },
        { label: 'Category', href: '/category' },
        { label: 'Item' },
      ]}
    />
  );
}

Click handlers (router integration)

import * as React from 'react';
import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';

export default function Example() {
  const navigate = (path: string) => {
    // your router's navigate fn
  };

  return (
    <Breadcrumbs
      items={[
        { label: 'Home', onClick: () => navigate('/') },
        { label: 'Settings', onClick: () => navigate('/settings') },
        { label: 'Profile' },
      ]}
    />
  );
}

Disabled item

import * as React from 'react';
import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';

export default function Example() {
  return (
    <Breadcrumbs
      items={[
        { label: 'Home', href: '/' },
        { label: 'Restricted', disabled: true },
        { label: 'Current Page' },
      ]}
    />
  );
}

Accessibility

• Container is <nav aria-label="Breadcrumb"> wrapping a semantic <ol>.
• The active (last) item carries aria-current="page" and is not focusable.
• Separators are decorative (aria-hidden).
• Disabled items are removed from the tab order (tabIndex={-1}).
• Items with href render as <a role="link">; items without href render as <div role="button" tabIndex={0}> — keyboard activation depends on the host environment, prefer href when navigating to a real URL.