Stepper

A multi-step progress indicator for B2B surfaces. Supports vertical and horizontal layouts, interactive step navigation, a chip-only "simple" mode, and an optional tinted surface container.

Prefer this over @xsolla/xui-stepper for all B2B surfaces.

Installation

npm install @xsolla/xui-b2b-stepper

Imports

import {
  Stepper,
  type StepperProps,
  type StepperDirection,
  type StepType,
  type StepStateType,
  type StepClickType,
} from "@xsolla/xui-b2b-stepper";

Quick start

import { Stepper } from "@xsolla/xui-b2b-stepper";

const steps = [
  {
    title: "Account details",
    description: "Name, email, password",
    state: "current" as const,
  },
  { title: "Billing", description: "Payment method" },
  { title: "Confirm", description: "Review and submit" },
];

<Stepper steps={steps} direction="vertical" />;

API Reference

<Stepper>

StepperProps extends Omit<BoxProps, "onClick">, so any Box layout/style prop (e.g. padding, width, style) is forwarded to the root.

| Prop | Type | Default | Description | | ------------- | ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | steps | StepType[] | — | Array of step definitions. | | direction | StepperDirection | "vertical" | Layout direction. | | surface | boolean | false | Wrap in a tinted surface card (background-secondary + overlay-mono, radius 8). | | simple | boolean | false | Render the chip only — no title, description, or caption. | | onClick | StepClickType | — | Called when a step is clicked. Receives { number, step }. | | aria-label | string | auto | Accessible label for the navigation. Defaults to "Stepper with N steps". | | className | string | — | CSS class applied to the root. | | ...BoxProps | — | — | Any other BoxProps are passed through (onClick is intentionally omitted from the Box type — the Stepper owns step-click semantics). |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

StepType

| Field | Type | Default | Description | | ------------- | --------------- | -------------- | ------------------------------------------------------------------ | | title | ReactNode | — | Step heading. | | description | ReactNode | — | Secondary text below the title. | | caption | ReactNode | — | Small caption rendered above the title (body-xs, tertiary colour). | | state | StepStateType | "incomplete" | Visual state of the step. | | disabled | boolean | false | Prevents click interaction. | | noClick | boolean | false | Suppresses click even when onClick is provided. | | key | string | index | Stable React key override. |

StepStateType

type StepStateType =
  | "current"
  | "incomplete"
  | "loading"
  | "complete"
  | "warning"
  | "alert";

| Value | Appearance | | ------------ | -------------------------------------------------------- | | current | Active step — highlighted chip, white card background. | | complete | Finished — checkmark icon in chip. | | incomplete | Future step — muted appearance. | | loading | In progress — spinner in chip, card background. | | warning | Needs attention — warning icon in chip, card background. | | alert | Error/failed — alert icon in chip, card background. |

StepperDirection

type StepperDirection = "horizontal" | "vertical";

StepClickType

type StepClickType = (args: { number: number; step: StepType }) => void;
// number: 1-based index of the clicked step

Examples

Horizontal stepper

import { Stepper } from "@xsolla/xui-b2b-stepper";

<Stepper steps={steps} direction="horizontal" />;

With surface container

Recommended when embedding inside a Drawer sidebar.

import { Stepper } from "@xsolla/xui-b2b-stepper";

<Stepper steps={steps} direction="vertical" surface />;

Interactive (clickable steps)

import { useState } from "react";
import { Stepper, type StepType } from "@xsolla/xui-b2b-stepper";

const STEPS = [
  { title: "Account details", description: "Name, email, password" },
  { title: "Billing", description: "Payment method" },
  { title: "Confirm", description: "Review and submit" },
];

function ClickableStepper() {
  const [active, setActive] = useState(1);

  const steps: StepType[] = STEPS.map((s, i) => ({
    ...s,
    state:
      i + 1 < active ? "complete" : i + 1 === active ? "current" : "incomplete",
  }));

  return (
    <Stepper
      steps={steps}
      direction="vertical"
      onClick={({ number }) => setActive(number)}
    />
  );
}

Simple (numbers only)

import { Stepper } from "@xsolla/xui-b2b-stepper";

<Stepper
  steps={[
    { title: "Step 1", state: "complete" },
    { title: "Step 2", state: "current" },
    { title: "Step 3" },
  ]}
  direction="horizontal"
  simple
/>;

With step captions

import { Stepper } from "@xsolla/xui-b2b-stepper";

<Stepper
  steps={[
    { caption: "Step 1", title: "Account details", state: "current" },
    { caption: "Step 2", title: "Billing" },
    { caption: "Step 3", title: "Confirm" },
  ]}
  direction="vertical"
/>;

All step states

import { Stepper } from "@xsolla/xui-b2b-stepper";

<Stepper
  direction="vertical"
  steps={[
    { title: "Complete", state: "complete" },
    { title: "Current", state: "current" },
    { title: "Loading", state: "loading" },
    { title: "Warning", state: "warning" },
    { title: "Alert", state: "alert" },
    { title: "Incomplete", state: "incomplete" },
  ]}
/>;

Accessibility

• Root has role="navigation" and an aria-label (defaults to "Stepper with N steps").
• The active step is marked with aria-current="step".
• Clickable steps use role="button", tabIndex={0}, and respond to Enter/Space.
• Disabled steps have aria-disabled="true".
• Connector lines are decorative; the trailing connector on the final step is hidden via aria-hidden.