Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Navigation

Stepper

An ordered process navigator with an active-step panel and optional linear flow.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add stepper

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Current panel: Details
Vue
<script setup lang="ts">
import { ref } from 'vue'
import Stepper from './components/ui/stepper/Stepper.vue'

const step = ref('details')
const steps = [
  { value: 'details', label: 'Details' },
  { value: 'payment', label: 'Payment' },
  { value: 'review', label: 'Review', optional: true },
]
</script>

<template>
  <div class="w-fit min-w-0 max-w-full">
    <Stepper
      v-model="step"
      :items="steps"
      optional-label="Optional"
      linear
      label="Checkout progress"
    >
      <template #default="{ item }">Current panel:&nbsp;{{ item.label }}</template>
    </Stepper>
  </div>
</template>

Markers stay fixed at 24px horizontally and 32px vertically. Label colors and the default number/check content fade locally when a step changes; no circle travels between steps. The vertical layout keeps its connecting rail and progress fill. Initial completion is rendered on the server, and reduced-motion preferences disable transitions. Custom indicator content remains available through the indicator slot.

When to use it

Checkout flow

Guide readers through details, payment, and final review in order.

Application process

Show the current stage while allowing revisits to completed sections.

More examples

Linear checkout

The application owns the content and decides when to advance.

Linear checkout
<script setup lang="ts">
import { ref } from 'vue'
import Button from './components/ui/button/Button.vue'
import Stepper from './components/ui/stepper/Stepper.vue'

const step = ref('details')
const steps = [
  { value: 'details', label: 'Details' },
  { value: 'payment', label: 'Payment' },
  { value: 'review', label: 'Review' },
]
</script>

<template>
  <Stepper v-model="step" :items="steps" linear label="Checkout steps">
    <template #default="{ item }">
      <section>
        <h2>{{ item.label }}</h2>
        <Button v-if="step === 'details'" @click="step = 'payment'">Continue</Button>
      </section>
    </template>
  </Stepper>
</template>

Optional stage

Identify optional work with application-owned text.

Optional stage
<script setup lang="ts">
import Stepper from './components/ui/stepper/Stepper.vue'

const steps = [
  { value: 'account', label: 'Account' },
  { value: 'profile', label: 'Profile', optional: true },
  { value: 'finish', label: 'Finish' },
]
</script>

<template>
  <Stepper :items="steps" optional-label="Optional" orientation="vertical" label="Setup progress">
    <template #default="{ item }"><p>Complete&nbsp;{{ item.label }} to continue.</p></template>
  </Stepper>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Stepper

Complete API for Stepper
NameType or signatureDefaultWhat it does
itemspropreadonly StepperItem[]RequiredData items displayed by this component.
orientationprop"horizontal" | "vertical" | undefined"horizontal"Arrange items horizontally or vertically.
linearpropboolean | undefinedNot setRequire steps to be completed in order.
labelpropstring | undefinedNot setVisible or accessible name for this item.
optionalLabelpropstring | undefinedNot setText announcing that this field is optional.
modelValuemodelstring | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: string | undefined]—Requests a new model value from the parent.
indicatorslot{ item: StepperItem; index: number; active: boolean; completed: boolean; }OptionalContent for the indicator area of Stepper.
labelslot{ item: StepperItem; }OptionalContent for the label area of Stepper.
defaultslot{ item: StepperItem; index: number; }OptionalContent shown inside Stepper.
Public type definitions
Public types
// packages/frameworks/vue/components/stepper/types.ts
export interface StepperItem {
  value: string
  label: string
  description?: string
  disabled?: boolean
  optional?: boolean
}

export interface StepperProps {
  items: readonly StepperItem[]
  orientation?: 'horizontal' | 'vertical'
  linear?: boolean
  label?: string
  optionalLabel?: string
}

Implementation notes

  • Validate the active panel before moving to the next step in application code.
  • Linear mode permits the next enabled step and revisits to completed steps.

Accessibility and localization

  • The active step exposes aria-current="step"; provide a meaningful label for the overall process.

Source contract and editing guidance