Navigation

Steppers for guided flows

Steppers show progress across ordered stages. Each StepperItem can surface an indicator, title, and supporting description while the root tracks the active index.

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order

Vertical

1
Draft
Autosaved
2
Review
Awaiting approval
3
Published
Live to readers

Stepper code examples

Use Show output / Show code on each row. Snippets start with a Variant line naming orientation, active step, and size.

Horizontal · appearance: complete

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: current

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: upcoming

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: sky

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: rose

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: purple

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: pink

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: orange

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: yellow

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: teal

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: indigo

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: emerald

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gray

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: violet

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-blue

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-green

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-red

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-yellow

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-purple

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-teal

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-indigo

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-pink

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

Horizontal · appearance: gradient-orange

1
Details
Confirm items
2
Payment
Billing method
3
Review
Submit order
4
Details
Confirm items
5
Payment
Billing method
6
Review
Submit order
7
Details
Confirm items
8
Payment
Billing method
9
Review
Submit order

VerticalSM

1
Draft
Autosaved
2
Review
Awaiting approval
3
Published
Live to readers

CSS variable overrides

Stepper CSS variables

Override these stepper variables on :root, a theme selector, or a component wrapper.

117 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-stepper-indicator-complete-border: oklch(69.6% 0.17 162.48 / 0.6);
  --zui-stepper-indicator-complete-bg: oklch(69.6% 0.17 162.48 / 0.2);
  --zui-stepper-indicator-complete-fg: oklch(37.8% 0.077 168.94);
  --zui-stepper-indicator-complete-ring: oklch(76.5% 0.177 163.223 / 0.3);
  --zui-stepper-indicator-current-border: oklch(54.1% 0.281 293.009);
  --zui-stepper-indicator-current-bg: oklch(60.6% 0.25 292.717 / 0.2);
  --zui-stepper-indicator-current-fg: oklch(20.8% 0.042 265.755);
  --zui-stepper-indicator-current-ring: oklch(70.2% 0.183 293.541 / 0.5);
  --zui-stepper-indicator-upcoming-border: #00000026;
  --zui-stepper-indicator-upcoming-bg: #0000000d;
  --zui-stepper-indicator-upcoming-fg: oklch(55.4% 0.046 257.417);
  --zui-stepper-indicator-sky-border: oklch(68.5% 0.169 237.323 / 0.6);
  --zui-stepper-indicator-sky-bg: oklch(68.5% 0.169 237.323 / 0.2);
  --zui-stepper-indicator-sky-fg: oklch(39.1% 0.09 240.876);
  --zui-stepper-indicator-sky-ring: oklch(74.6% 0.16 232.661 / 0.3);
  --zui-stepper-indicator-rose-border: oklch(64.5% 0.246 16.439 / 0.6);
  --zui-stepper-indicator-rose-bg: oklch(64.5% 0.246 16.439 / 0.2);
  --zui-stepper-indicator-rose-fg: oklch(41% 0.159 10.272);
  --zui-stepper-indicator-rose-ring: oklch(71.2% 0.194 13.428 / 0.3);
  --zui-stepper-indicator-purple-border: oklch(62.7% 0.265 303.9 / 0.6);
  --zui-stepper-indicator-purple-bg: oklch(62.7% 0.265 303.9 / 0.2);
  --zui-stepper-indicator-purple-fg: oklch(38.1% 0.176 304.987);
  --zui-stepper-indicator-purple-ring: oklch(71.4% 0.203 305.504 / 0.3);
  --zui-stepper-indicator-pink-border: oklch(65.6% 0.241 354.308 / 0.6);
  --zui-stepper-indicator-pink-bg: oklch(65.6% 0.241 354.308 / 0.2);
  --zui-stepper-indicator-pink-fg: oklch(40.8% 0.153 2.432);
  --zui-stepper-indicator-pink-ring: oklch(71.8% 0.202 349.761 / 0.3);
  --zui-stepper-indicator-orange-border: oklch(70.5% 0.213 47.604 / 0.6);
  --zui-stepper-indicator-orange-bg: oklch(70.5% 0.213 47.604 / 0.2);
  --zui-stepper-indicator-orange-fg: oklch(40.8% 0.123 38.172);
  --zui-stepper-indicator-orange-ring: oklch(75% 0.183 55.934 / 0.3);
  --zui-stepper-indicator-yellow-border: oklch(79.5% 0.184 86.047 / 0.6);
  --zui-stepper-indicator-yellow-bg: oklch(79.5% 0.184 86.047 / 0.2);
  --zui-stepper-indicator-yellow-fg: oklch(42.1% 0.095 57.708);
  --zui-stepper-indicator-yellow-ring: oklch(85.2% 0.199 91.936 / 0.3);
  --zui-stepper-indicator-teal-border: oklch(70.4% 0.14 182.503 / 0.6);
  --zui-stepper-indicator-teal-bg: oklch(70.4% 0.14 182.503 / 0.2);
  --zui-stepper-indicator-teal-fg: oklch(38.6% 0.063 188.416);
  --zui-stepper-indicator-teal-ring: oklch(77.7% 0.152 181.912 / 0.3);
  --zui-stepper-indicator-indigo-border: oklch(58.5% 0.233 277.117 / 0.6);
  --zui-stepper-indicator-indigo-bg: oklch(58.5% 0.233 277.117 / 0.2);
  --zui-stepper-indicator-indigo-fg: oklch(35.9% 0.144 278.697);
  --zui-stepper-indicator-indigo-ring: oklch(67.3% 0.182 276.935 / 0.3);
  --zui-stepper-indicator-emerald-border: oklch(69.6% 0.17 162.48 / 0.6);
  --zui-stepper-indicator-emerald-bg: oklch(69.6% 0.17 162.48 / 0.2);
  --zui-stepper-indicator-emerald-fg: oklch(37.8% 0.077 168.94);
  --zui-stepper-indicator-emerald-ring: oklch(76.5% 0.177 163.223 / 0.3);
  --zui-stepper-indicator-gray-border: oklch(55.1% 0.027 264.364 / 0.6);
  --zui-stepper-indicator-gray-bg: oklch(55.1% 0.027 264.364 / 0.2);
  --zui-stepper-indicator-gray-fg: oklch(21% 0.034 264.665);
  --zui-stepper-indicator-gray-ring: oklch(70.7% 0.022 261.325 / 0.3);
  --zui-stepper-indicator-violet-border: oklch(60.6% 0.25 292.717 / 0.6);
  --zui-stepper-indicator-violet-bg: oklch(60.6% 0.25 292.717 / 0.2);
  --zui-stepper-indicator-violet-fg: oklch(38% 0.189 293.745);
  --zui-stepper-indicator-violet-ring: oklch(70.2% 0.183 293.541 / 0.3);
  --zui-stepper-indicator-gradient-blue-border: oklch(62.3% 0.214 259.815 / 0.6);
  --zui-stepper-indicator-gradient-blue-bg: oklch(62.3% 0.214 259.815 / 0.2);
  --zui-stepper-indicator-gradient-blue-fg: oklch(37.9% 0.146 265.522);
  --zui-stepper-indicator-gradient-blue-ring: oklch(70.7% 0.165 254.624 / 0.3);
  --zui-stepper-indicator-gradient-green-border: oklch(72.3% 0.219 149.579 / 0.6);
  --zui-stepper-indicator-gradient-green-bg: oklch(72.3% 0.219 149.579 / 0.2);
  --zui-stepper-indicator-gradient-green-fg: oklch(39.3% 0.095 152.535);
  --zui-stepper-indicator-gradient-green-ring: oklch(79.2% 0.209 151.711 / 0.3);
  --zui-stepper-indicator-gradient-red-border: oklch(63.7% 0.237 25.331 / 0.6);
  --zui-stepper-indicator-gradient-red-bg: oklch(63.7% 0.237 25.331 / 0.2);
  --zui-stepper-indicator-gradient-red-fg: oklch(39.6% 0.141 25.723);
  --zui-stepper-indicator-gradient-red-ring: oklch(70.4% 0.191 22.216 / 0.3);
  --zui-stepper-indicator-gradient-yellow-border: oklch(79.5% 0.184 86.047 / 0.6);
  --zui-stepper-indicator-gradient-yellow-bg: oklch(79.5% 0.184 86.047 / 0.2);
  --zui-stepper-indicator-gradient-yellow-fg: oklch(42.1% 0.095 57.708);
  --zui-stepper-indicator-gradient-yellow-ring: oklch(85.2% 0.199 91.936 / 0.3);
  --zui-stepper-indicator-gradient-purple-border: oklch(62.7% 0.265 303.9 / 0.6);
  --zui-stepper-indicator-gradient-purple-bg: oklch(62.7% 0.265 303.9 / 0.2);
  --zui-stepper-indicator-gradient-purple-fg: oklch(38.1% 0.176 304.987);
  --zui-stepper-indicator-gradient-purple-ring: oklch(71.4% 0.203 305.504 / 0.3);
  --zui-stepper-indicator-gradient-teal-border: oklch(70.4% 0.14 182.503 / 0.6);
  --zui-stepper-indicator-gradient-teal-bg: oklch(70.4% 0.14 182.503 / 0.2);
  --zui-stepper-indicator-gradient-teal-fg: oklch(38.6% 0.063 188.416);
  --zui-stepper-indicator-gradient-teal-ring: oklch(77.7% 0.152 181.912 / 0.3);
  --zui-stepper-indicator-gradient-indigo-border: oklch(58.5% 0.233 277.117 / 0.6);
  --zui-stepper-indicator-gradient-indigo-bg: oklch(58.5% 0.233 277.117 / 0.2);
  --zui-stepper-indicator-gradient-indigo-fg: oklch(35.9% 0.144 278.697);
  --zui-stepper-indicator-gradient-indigo-ring: oklch(67.3% 0.182 276.935 / 0.3);
  --zui-stepper-indicator-gradient-pink-border: oklch(65.6% 0.241 354.308 / 0.6);
  --zui-stepper-indicator-gradient-pink-bg: oklch(65.6% 0.241 354.308 / 0.2);
  --zui-stepper-indicator-gradient-pink-fg: oklch(40.8% 0.153 2.432);
  --zui-stepper-indicator-gradient-pink-ring: oklch(71.8% 0.202 349.761 / 0.3);
  --zui-stepper-indicator-gradient-orange-border: oklch(70.5% 0.213 47.604 / 0.6);
  --zui-stepper-indicator-gradient-orange-bg: oklch(70.5% 0.213 47.604 / 0.2);
  --zui-stepper-indicator-gradient-orange-fg: oklch(40.8% 0.123 38.172);
  --zui-stepper-indicator-gradient-orange-ring: oklch(75% 0.183 55.934 / 0.3);
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-stepper-indicator-complete-fg-dark: oklch(95% 0.052 163.051);
  --zui-stepper-indicator-current-border-dark: oklch(70.2% 0.183 293.541);
  /* ...same variables with -dark at the end */
}

Overview

Orientation switches between horizontal stacks for top-of-page flows and vertical stacks for side rails. Indicators default to numeric labels but accept custom content.

Common use cases

Checkout and payment flows.
Account onboarding and KYC.
Publishing pipelines with approvals.
Support ticket escalation stages.

FAQ

How is the active step determined?

Pass activeStep as a zero-based index. Steps before the index render as complete, the matching index renders as current, and later steps render as upcoming.

Does the stepper use a real list element?

The root uses role="list" with listitem roles on items so separators and layout can stay flexible without breaking list semantics.