Stepper

A cross-platform stepper that displays progress through a sequence of steps in horizontal or vertical layouts; ships alongside ProgressStep and ProgressStepItem for compact arrow-style indicators.

[!NOTE] Deprecated for B2B surfaces — use @xsolla/xui-b2b-stepper, which implements the current Figma design. This package remains available for existing consumers and will be removed in a future release.

Installation

npm install @xsolla/xui-stepper

Imports

import {
  Stepper,
  Step,
  ProgressStep,
  ProgressStepItem,
} from "@xsolla/xui-stepper";
import type {
  StepperProps,
  StepType,
  StepStateType,
  StepperDirectionType,
  StepperUIVariantType,
  StepperPaletteType,
  StepperSize,
  StepClickType,
  ProgressStepProps,
  ProgressStepItemProps,
  ProgressStepItemState,
  ProgressStepSize,
} from "@xsolla/xui-stepper";

Quick start

const steps = [
  { title: "Account", state: "complete" as const },
  { title: "Payment", state: "current" as const },
  { title: "Review", state: "incomplete" as const },
];

<Stepper steps={steps} />;

API Reference

<Stepper>

| 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[] | — | Step definitions. | | direction | 'horizontal' \| 'vertical' | 'horizontal' | Layout direction. | | size | 'sm' \| 'md' | 'md' | Step size. | | variantUI | 'current' \| 'simple' | 'current' | Visual variant. | | palette | 'brand' \| 'brandSecondary' | 'brand' | Colour palette. | | tail | boolean | false | Show connecting lines (simple variant). | | onClick | StepClickType | — | Fired when a step is clicked. | | className | string | — | Class applied to the root container; customClass is also accepted and concatenated for backwards compatibility. | | aria-label | string | — | Accessible label for the stepper. |

Stepper also accepts standard BoxProps (excluding onClick).

Inherits ThemeOverrideProps (themeMode, themeProductContext).

<ProgressStep>

A compact arrow-style progress indicator.

| Prop | Type | Default | Description | | ------------- | ------------------------ | ------- | -------------------------------------- | | count | number | — | Total number of steps. | | activeStep | number | — | Zero-based active step index. | | size | 'sm' \| 'md' | 'md' | Indicator size. | | arrows | boolean | true | Show prev/next arrow buttons. | | onStepPress | (step: number) => void | — | Fired when navigation moves to a step. | | className | string | — | Class on the root container. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

<ProgressStepItem>

Single dot used by ProgressStep; can be composed manually.

| Prop | Type | Default | Description | | -------------- | ---------------------------------- | ----------- | -------------------- | | state | 'active' \| 'default' \| 'hover' | 'default' | Visual state. | | size | 'sm' \| 'md' | 'md' | Dot size. | | onPress | () => void | — | Press handler. | | onMouseEnter | () => void | — | Mouse-enter handler. | | onMouseLeave | () => void | — | Mouse-leave handler. | | className | string | — | Custom class. |

<Step>

Internal step renderer used by Stepper; exported for advanced layouts. Props mirror StepType (see Types below) plus the layout context props the parent Stepper injects (size, direction, variantUI, palette, stepNumber, tail, isLast, onClick).

Types

type StepperDirectionType = "horizontal" | "vertical";
type StepperUIVariantType = "current" | "simple";
type StepperPaletteType = "brand" | "brandSecondary";
type StepperSize = "sm" | "md";
type StepStateType =
  | "current"
  | "incomplete"
  | "loading"
  | "complete"
  | "alert"
  | "warning";
type StepClickType = (args: { number: number; step: StepType }) => void;

interface StepType {
  title: string | ReactElement;
  description?: string | ReactElement;
  state?: StepStateType;
  disabled?: boolean;
  key?: string;
  noClick?: boolean;
}

Examples

Vertical with descriptions

<Stepper
  direction="vertical"
  steps={[
    { title: "Email", description: "Verify your email", state: "complete" },
    { title: "Profile", description: "Set up your profile", state: "current" },
    {
      title: "Preferences",
      description: "Customise settings",
      state: "incomplete",
    },
  ]}
/>

Step states

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

Simple variant with tail

<Stepper variantUI="simple" tail steps={steps} />

Progress step

const [step, setStep] = useState(0);

<ProgressStep count={5} activeStep={step} onStepPress={setStep} />;

Accessibility

• Root uses role="navigation" for semantic meaning.
• Steps are keyboard accessible when clickable; disabled steps are announced.
• aria-label on the stepper provides context for assistive technology.
• Step state is conveyed both visually and via accessible names.