Bridge UI

Stepper

Multi-step flow indicator for checkout, onboarding, and wizards.

Introduction

Stepper shows progress through an ordered flow—checkout, onboarding, and wizards. Compose with Step. The indicator uses numbered circles and a connector; completed steps show a check. Wizard footer actions (Next / Back) stay in the app.

When to use: Discrete stages the user moves through in sequence. Optional click-to-navigate when steps are completed or linear is off.

Compared to similar components:

  • Progress — A labeled bar for continuous work (uploads, determinate percentages). Prefer Progress for a track; use Stepper for named stages.
  • Tabs — Peer views on the same level. Prefer Tabs when order does not matter; use Stepper when later steps depend on earlier ones.
  • Breadcrumb — Where the user is in a hierarchy. Prefer Breadcrumb for location; use Stepper for process.

Use the framework selector in the site header to switch between React and Vue.

Import

import { Stepper } from "@bridge-ui/vue/Components/Stepper";
import { Step } from "@bridge-ui/vue/Components/Step";
import { Stepper } from "@bridge-ui/react/Components/Stepper";
import { Step } from "@bridge-ui/react/Components/Step";

Basic usage

Bind the 0-based active index with activeStep and onChange (React) or v-model (Vue). Uncontrolled React usage starts at defaultActiveStep (0). Completed steps (indexes before the active step) render a check in the indicator.

Vertical

Set orientation="vertical" to stack steps. Pass description for secondary text, and children (Vue: default slot) for a body shown under the active step.

Non-linear

By default linear is on: users can select the current step and completed steps, but not incomplete upcoming ones. Set linear to false to allow jumping to any enabled step.

Error and disabled

error forces error styling on the indicator (it wins over completed and active). disabled makes that step non-interactive.

Colors

Use the color prop for the active and completed accent. Available colors: primary, secondary, success, info, warning, error, and dark.

Sizes

Change indicator and label scale with size: sm, md (default), and lg.

Customization

Fine-tune appearance with the classes prop. On Stepper, target root and list. On Step, target root, connector, trigger, indicator, icon, label, description, and content.

Accessibility

  • The root renders a nav with aria-label="Progress" by default. Override with your own aria-label when the page has more than one stepper or when a more specific name helps (for example “Checkout”).
  • The active step trigger gets aria-current="step". Error steps set aria-invalid.
  • Connector lines are aria-hidden. Vertical step bodies are labelled by the matching trigger via aria-labelledby.
  • Arrow keys, Home, and End move focus among clickable steps. Linear mode still blocks selecting incomplete upcoming steps.
  • Do not rely on color alone for error or completion; the check, error icon, and labels provide the extra signal.

Anatomy

<nav aria-label="Progress"> <!-- Stepper root -->
  <ol> <!-- list -->
    <li> <!-- Step root -->
      <div> <!-- connector -->
      <button> <!-- trigger -->
        <span> <!-- indicator: number, check, error icon, or slots.icon -->
        <span> <!-- text -->
          <span> <!-- label -->
          <span> <!-- description -->
      <div> <!-- content (vertical + active only) -->
    </li>
  </ol>
</nav>

Target Stepper parts with classes: root, list. Target Step parts with root, connector, trigger, indicator, icon, label, description, and content.

Progress, Tabs, Breadcrumb, Pagination

API

Stepper

Prop Type Default Description
@change (step: number) => void — Same payload as model updates.
@update:model-value (step: number) => void — Emitted when the active index changes.
v-model / modelValue number 0 Controlled 0-based active index.
Prop Type Default Description
activeStep number — Controlled 0-based active index.
defaultActiveStep number 0 Initial index when uncontrolled.
onChange (step: number) => void — Called when the active index changes.
Prop Type Default Description
children ReactNode — Compound steps (Step). Use the default slot in Vue.
classes StepperClasses — Classes for root and list.
color StepperColor "primary" Accent for active and completed steps.
customProps StepperCustomProps — Extra props for root and list.
linear boolean true When true, block jumping ahead of incomplete steps.
orientation StepperOrientation "horizontal" Layout direction.
size StepperSize "md" Indicator and label scale.

Step

Prop Type Default Description
children body content — Shown under the step when orientation="vertical" and the step is active. Vue: default slot.
classes StepClasses — Classes for step parts.
completed boolean derived Force completed (true) or incomplete (false). Omit to derive from index vs active step.
customProps StepCustomProps — Extra props for root, trigger, indicator, icons, and content.
description ReactNode / Vue string — Secondary text under the label. Override with the description slot.
disabled boolean false Non-interactive step.
error boolean false Error styling on the indicator. Wins over completed and active.
icon IconSource — Override the default numeric / check / error indicator.
label ReactNode / Vue string — Step title. Override with the label slot.
slots { icon?, label?, description? } — Custom indicator, title, or description (React). Vue: #icon, #label, #description.