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). | | target | '_self' \| '_blank' \| '_parent' \| '_top' \| string | Browsing context, forwarded to the underlying <a target>. Anything other than '_self' makes the item a plain link — onClick is never invoked for it. | | rel | string | rel attribute for the link. Defaults to 'noopener noreferrer' when target="_blank" and no explicit value is given. | | onClick | (event?: BreadcrumbItemClickEvent) => void | Click handler. Not invoked when the item is active or disabled. See Links and in-app routing. | | disabled | boolean | Reduces opacity, removes tab stop, and prevents interaction. |

Links and in-app routing

An item can be a real link and drive the router at the same time — set both href and onClick.

| Interaction | What happens | | --- | --- | | Plain left click | preventDefault() runs, then onClick(event) is called. No document navigation. | | Cmd / Ctrl / Shift / Alt click | Falls through to the browser — opens the href in a new tab or window. onClick is not called. | | Middle click (button !== 0) | Falls through to the browser. onClick is not called. | | Right click → Copy link address | Yields the real href, because it is a genuine <a href> in the DOM. | | target other than '_self' | Always a plain link — onClick is not called for any click. | | onClick with no href | Renders role="button"; every activation calls the handler. Nothing is prevented. | | Event already defaultPrevented | Treated as handled upstream — onClick is not called. |

This mirrors the guard react-router's <Link> applies, so a crumb keeps normal link affordances (new tab, new window, copy link, crawlable href) while still routing client-side on a plain click.

On React Native there is no mouse event: button and the modifier keys are absent, so onClick always runs.

onClick receives the click event (BreadcrumbItemClickEvent, a structural subset that compiles on both platforms). The old zero-argument onClick: () => void signature is still valid.

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' },
      ]}
    />
  );
}

Real links plus router integration (recommended)

Keep the href so the crumb is crawlable and openable in a new tab, and add onClick for client-side navigation.

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

export default function Example() {
  const navigate = useNavigate();

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

Click handlers only (no URL)

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' },
      ]}
    />
  );
}

External link in a new tab

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

export default function Example() {
  return (
    <Breadcrumbs
      items={[
        { label: 'Home', href: '/' },
        { label: 'Docs', href: 'https://xsolla.com', target: '_blank' },
        { label: 'Current Page' },
      ]}
    />
  );
}

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.
• target="_blank" items get rel="noopener noreferrer" unless you pass your own rel.