vue-stepper

library1.4.2jsnpmunverified

Vue Stepper is a lightweight, horizontal stepper component designed for Vue.js applications, facilitating the creation of multi-step forms or guided processes. The current stable version is 1.4.2. Its release cadence shows regular, albeit minor, updates primarily focused on adding new language translations, with core features evolving less frequently (e.g., reset functionality in 1.4.0, event improvements in 1.0.10, and behavior changes in 1.0.8). Key differentiators include its simplicity, event-driven nature for controlling navigation, the ability to use custom Vue components as step content, and configurable features like top-buttons and step persistence via `keep-alive`. It provides explicit events for navigation (e.g., `completed-step`, `active-step`, `stepper-finished`, `clicking-back`) and allows granular control over step progression using the `can-continue` event from within content components. The component also supports various locales for button texts.

web-framework

npm install vue-stepper

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-STEPPER

vue-stepper

web-frameworkjavascriptv1.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HorizontalStepper

✓ import HorizontalStepper from 'vue-stepper';

✗ import { HorizontalStepper } from 'vue-stepper';

The primary component is a default export. While its internal name might be 'StepperComponent', it's commonly imported and used as 'HorizontalStepper' to match the HTML tag `<horizontal-stepper>`. Using named import will result in an undefined error.

This quickstart demonstrates how to integrate `vue-stepper` into a Vue 3 application using the Composition API. It shows component registration, defining steps with custom content components, and handling key events like `completed-step`, `stepper-finished`, `clicking-back`, and `reset` events.

<template> <section class="section"> <div class="container"> <div class="columns"> <div class="column is-8 is-offset-2"> <HorizontalStepper :steps="demoSteps" @completed-step="completeStep" @stepper-finished="stepperFinished" @clicking-back="clickingBack" @reset="resetStepper" locale="en" :top-buttons="true" :keep-alive="true" /> </div> </div> </div> </section> </template> <script setup lang="ts"> import { ref } from 'vue'; import HorizontalStepper from 'vue-stepper'; // Define your step content components as Vue components // These would typically be in separate .vue files. const StepOne = { template: '<div><h3>Step 1 Content</h3><p>Fill out details.</p><button @click="$emit(\'can-continue\', {value: true})">Mark as Ready</button></div>' }; const StepTwo = { template: '<div><h3>Step 2 Content</h3><p>More information here.</p><button @click="$emit(\'can-continue\', {value: true})">Proceed</button></div>' }; const StepThree = { template: '<div><h3>Step 3 Content (Final)</h3><p>Review and submit.</p></div>' }; const demoSteps = ref([ { icon: 'mail', name: 'first', title: 'Email', subtitle: 'Add your email', component: StepOne, completed: false }, { icon: 'lock', name: 'second', title: 'Password', subtitle: 'Enter your password', component: StepTwo, completed: false }, { icon: 'check', name: 'third', title: 'Confirmation', subtitle: 'Confirm details', component: StepThree, completed: false } ]); const completeStep = (payload: { name: string, index: number }) => { console.log('Completed step:', payload.name, payload.index); if (demoSteps.value[payload.index]) { demoSteps.value[payload.index].completed = true; } }; const stepperFinished = () => { alert('Stepper process completed!'); console.log('Final submission logic would go here.'); }; const clickingBack = (payload: { name: string, index: number }) => { console.log('Navigating back to step:', payload.name, payload.index); } const resetStepper = () => { console.log('Stepper reset event triggered. Re-initializing form data.'); // Logic to reset form data or component states demoSteps.value.forEach(step => step.completed = false); } </script> <style> /* Basic styling for demonstration, e.g., for 'section' and 'container' */ .section { padding: 20px; } .container { max-width: 800px; margin: auto; } .columns { display: flex; justify-content: center; } .column { width: 100%; } </style>

Debug

Known issues

breakingSince version 1.0.8, the internal `canContinue` variable in the stepper is automatically set to `false` on every next step. This means the 'Next' button will be disabled by default unless your custom step component explicitly emits the `can-continue` event with `{ value: true }`.

fix

Ensure all custom step components emit the `can-continue` event with `{ value: true }` when the step is ready for progression. For example: `this.$emit('can-continue', {value: true});`

affects: >=1.0.8

gotchaEach step object in the `steps` array must have a unique `name` property. Duplicate step names can lead to unpredictable navigation behavior or rendering issues.

fix

Verify that all `name` properties within your `steps` array are distinct strings.

affects: >=1.0.4

gotchaThe `icon` property for steps relies on the Material Icons library for rendering. If icons are not appearing correctly, ensure you have included the Material Icons stylesheet or font in your project.

fix

Add `<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">` to your HTML head or import the Material Icons CSS into your main stylesheet.

affects: >=1.0.4

gotchaThe `keep-alive` prop's default value changed to `true` in version 1.0.8. This prevents step components from being destroyed on step change, preserving their state. If you require components to unmount and remount (e.g., for fresh data fetching), you must explicitly set `keep-alive` to `false`.

fix

Set the `:keep-alive="false"` prop on the `<HorizontalStepper>` component if you need step components to re-initialize when navigating between steps.

affects: >=1.0.8

Errors

Common errors & fixes

Next button is always disabled

The current step's content component has not emitted the `can-continue` event with `{value: true}` to enable progression.

fix

Ensure your custom step component emits `this.$emit('can-continue', {value: true})` (or `emit('can-continue', {value: true})` in Composition API) when the step's content is valid or ready to proceed.

Icons are not showing up (e.g., mail, lock)

The Material Icons library CSS is not included in the project's main HTML or CSS, preventing the browser from rendering the specified icon fonts.

fix

Include the Material Icons stylesheet in your HTML `<head>` or import it into your main CSS file. For example, add `<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">` to your `index.html` or equivalent.

Error: Component 'MyStepComponent' is not defined (where MyStepComponent is your custom step component)

The custom component specified in the `component` property of a step object is not properly imported or registered in the Vue component where `HorizontalStepper` is used.

fix

Ensure your custom step components (e.g., `StepOne`, `StepTwo`) are correctly imported and available in the scope where `HorizontalStepper` is utilized, typically by importing them in your `<script setup>` block or listing them in the `components` option of your parent component.

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

vuerequiredThis is a Vue.js component and requires Vue as a peer dependency for its runtime. While not explicitly listed in package.json for this type of component, Vue is fundamental to its operation.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PygmySlowLoris/vue-stepper ↗

packagehttps://www.npmjs.com/package/vue-stepper ↗