Stepper

Stable v1.0.2

Step-by-step navigation for wizards and multi-stage forms. Works as a horizontal flow or a vertical sidebar, with error states per step.

1. Interactive Playground

Configure layout variants, orientation alignments, and flow rules in real-time.

Architecture

Orientation:

Horizontal

Label Alignment:

Right Inline

Appearance

Style Variant:

Solid Base

Severity Theme:

Primary

Node Sizing:

Medium (md)

Logic Constraints

Strict Linear Flow

When linear is active, users cannot manually click ahead to uncompleted steps. Try toggling this to test jumping around.

StepItem Fields

Show Step Icons

Error on Active Step

Disable Next Step

Awaiting platform click events...

Playground Component Integration

<Stepper
  v-model="activeStep"
  :items="steps"
/>

2. Complex Master-Detail Sidebar Wizard

By defining orientation="sidebar", the Stepper isolates the navigation inside a boxed menu, and exposes a permanent right-side panel for the #content slot. Flawless on desktop, automatically responsive on mobile.

Sidebar Slot Binding

<Stepper
  v-model="step"
  :items="items"
  orientation="sidebar"
  variant="soft"
>
  <!-- Renders at the very top of the Sidebar panel -->
  <template #sidebar-header>
    <div class="border-b pb-4 mb-2">
      <h3>Account Setup</h3>
    </div>
  </template>

  <!-- Renders automatically on the right side on desktop, stacked on mobile -->
  <template #content="{ index, active, error }">
    <div class="bg-content p-8 rounded-2xl border">

      <h2>{{ items[index].label }}</h2>

      <div v-if="index === 0">
        <InputText label="Full Name" />
      </div>

      <!-- Navigation Controls -->
      <div class="mt-8 flex justify-between pt-4 border-t">
        <Button label="Back" @click="step--" />
        <Button label="Save & Next" @click="step++" />
      </div>

    </div>
  </template>
</Stepper>

API Reference

Complete technical specifications for the Stepper component.

Props

Prop / Event	Type / Payload	Default	Description
v-model	number	0	The active step index (zero-based). Supports v-model binding.
items	StepItem[]	[] (Required)	Array of configurations defining each step node.
orientation	"horizontal" \| "vertical" \| "sidebar"	"horizontal"	Directional layout. Vertical/Sidebar modes expose the #content slot.
labelPosition	"bottom" \| "right"	"right"	Alignment of the label text relative to the node (Horizontal only).
variant	"solid" \| "soft" \| "outline"	"solid"	Determines the background and border rendering engine for nodes.
linear	boolean	true	Strict mode: users cannot click ahead to uncompleted steps manually.
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	"md"	Optical scaling for nodes, fonts, icons, and connecting lines.
severity	"primary" \| "secondary" \| "success" \| "info" \| "warning" \| "danger"	"primary"	Semantic color theme applied to active and completed steps.

Events (Emits)

Prop / Event	Type / Payload	Default	Description
update:modelValue	(index: number)	-	Fired when the step changes. Enables standard v-model binding.
change	(newIndex: number, oldIndex: number)	-	Fired specifically when a user manually clicks a step node.

StepItem Object Configuration

Prop / Event	Type / Payload	Default	Description
label	string	Required	Primary title text of the step.
description	string	undefined	Secondary sub-text below the primary label.
icon	string	undefined	Lucide icon string. Replaces the default numeric index.
error	boolean	false	Forces the step into a red warning state with an alert icon.
disabled	boolean	false	Makes the step completely unclickable, regardless of linear rules.
optional	boolean	false	Renders an "OPTIONAL" pill badge next to the label.

Slots

Slot Name	Exposed Bindings	Description
icon	{ step, index, active, completed, error }	Overrides the icon or number rendered inside the node circle.
title	{ step, index, active, completed, error }	Replaces the primary label text.
description	{ step, index, active, completed, error }	Replaces the secondary description text.
sidebar-header	-	Injects content above the steps inside the Sidebar Box (Sidebar orientation only).
sidebar-footer	-	Injects content below the steps inside the Sidebar Box (Sidebar orientation only).
content	{ step, index, active, completed, error }	Injects content dynamically. Renders as an accordion in "vertical", or as a right-panel in "sidebar".