Stepper

Components/Navigation

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/stepper

Overview

Copy

Stepper displays the path a user needs to follow to complete a process.

Do

  • Use it to divide a complex form or a process into a sequence of steps.
  • Use it to let users navigate across different steps.

Don't

  • Don't use it to display users' location on a website. Use <Breadcrumbs/> instead.
  • Don't use it to split up large amounts of data into multiple pages. Use <Pagination/> instead.
  • Don't use it for static progress indication. Use <LinearProgressBar/> instead.

Feature examples

Type

Control stepper appearance with type prop:

  • Use circle (default) in all common cases.
  • Use text in dense layouts.
Copy

Size

Control the size of the stepper with size property:

  • medium (default)
  • small
Copy

Fit mode

Control how component fits in the parent container with fit prop:

  • Use compact (default) to set the stepper width based on its content.
  • Use stretched to fill in all available space.
Copy

States

Control the state of each step individually with type prop:

  • Use normal (default) for non completed steps.
  • Use completed for previously completed steps.
  • Use error for steps with incomplete information or other issues.
  • Use disabled to indicate that step cannot be interacted with at a given moment.
Copy

Common use case examples

Multi-step flow

Split a long form into steps and demonstrate the user's progress.

Use linear or nonlinear Stepper logic for navigation based on your form content:

  • In linear logic, users cannot go back to previous steps or check future steps. Disable steps that they cannot navigate to.
  • In nonlinear logic, users can freely move across all steps.
Copy

Composers

Use stepper in composer header to split a complex flow into smaller steps.

Copy

Code

Copy

Props

NameTypeDefaultDescription
activeStepnumber—Sets the index of the active step. When not set, no step is active.
dataHookstring—Hook for testing purposes.
fit"stretched" | "compact"'compact'Fit mode for steps. In stretched mode the component grows to fill the parent container width.
onClick(index: number) => void—Event triggered on step click: onClick(stepIndex)
size"small" | "medium"'small'Sets the size of the items.
steps (required)StepperStep[]—An array of steps, where each step is an object with the following properties: - text - step title text (required). - type - step type (completed, disabled, error or default normal).
type"circle" | "text"'circle'Style type.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 1.343.0 (2026-10-26) — breaking: under WixDesignSystemProvider with mobile the steps now form a single horizontally scrolling row that keeps the active step in view and shows only its title, while the other steps show just their marker. (#17326) — has visual changes
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.277.0 (2026-05-07) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.205.0 (2025-07-15) — breaking: tokenization (#15056)
  • 1.143.0 (2024-11-25) — feat: size added (#14298)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?