OverStepper-vue

OverStepper-vue is a small, Vue 3 stepper component library inspired by the working StatusSection.vue prototype.

It is designed to be easy to drop into a project, while still giving you enough control for real workflows:

• horizontal or vertical layout
• configurable step transitions through a dependency list
• info and error badges on any step
• v-model support
• onChange callback before the step is committed
• optional plugin install

Quick start

Install the package:

npm install overstepper-vue

Use it in a component:

<script setup lang="ts">
import { ref } from 'vue'
import OverStepper from 'overstepper-vue'
import type { OverStepperBadge, OverStepperDependency, OverStepperStep } from 'overstepper-vue'

const currentStep = ref(1)

const steps: OverStepperStep<number>[] = [
  { value: 1, title: 'Draft', description: 'Initial state' },
  { value: 2, title: 'Review', description: 'Waiting for approval' },
  { value: 3, title: 'Done', description: 'Final state' }
]

const dependencies: OverStepperDependency<number>[] = [
  { from: 1, to: 2 },
  { from: 2, to: 3 }
]

const badges: OverStepperBadge<number>[] = [
  {
    value: 2,
    type: 'info',
    title: 'Heads up',
    description: 'This step needs extra attention.'
  },
  {
    value: 3,
    type: 'error',
    title: 'Blocked',
    description: 'This step is currently blocked.'
  }
]

function handleChange(payload) {
  console.log('changed:', payload)
}
</script>

<template>
  <OverStepper
    v-model="currentStep"
    :steps="steps"
    orientation="horizontal"
    :dependencies="dependencies"
    :badges="badges"
    :on-change="handleChange"
  />
</template>

The package injects its styles automatically when you import overstepper-vue. If you prefer to load the CSS manually, you can also import overstepper-vue/style.css. The package now reads theme colors from your app's CSS variables first (--background, --foreground, --primary, etc.), so it follows your light/dark theme instead of forcing a white palette.

Props

modelValue

The currently selected step value.

steps

The ordered list of steps to show.

orientation

Choose between:

• horizontal
• vertical

dependencies

Controls which steps can be reached from the current step.

Each item is a pair:

{ from: 1, to: 2 }

When dependencies are provided, the component allows both directions for that pair:

• 1 -> 2
• 2 -> 1

This makes it easy to support workflows where users can move forward and back.

badges

Attach a badge to any step value.

Supported badge types:

• info
• error

onChange

A callback that runs before the new step is applied.

Return false to cancel the change.

disabled

Disables all user interaction.

linear

Fallback mode that allows only the next step when no dependencies are defined.

Plugin usage

If you prefer global registration:

import { createApp } from 'vue'
import OverStepperVue from 'overstepper-vue'
import App from './App.vue'

createApp(App).use(OverStepperVue).mount('#app')

Local demo

This repository also includes a small demo page so you can try the component locally.

Run:

npm run dev

The demo shows:

• horizontal stepper with dependency rules
• vertical stepper with string values
• linear fallback mode
• info and error badges
• the onChange callback in action

Build

npm run build

Package name

The npm package name is overstepper-vue.