Vue 3 skeleton components to easily help you build the best stepper/wizzard you've ever made!

• Update this README to someting useful, like documentation
  • https://strawpoll.com/XOgOVJpRrn3
    • It's bad
    • It's not that bad
    • It could be better
    • It's ok
    • It's good
    • It's very good
    • It's the best documentation I've ever seen
• Prepare components for production
• Update NPM
• Add tests
• Better typing (help needed)

pnpm add vue-stappen
# or
yarn install vue-stappen
# or
yarn add vue-stappen

Starting off you will be presented a default and very minimal "skeleton" stepper/wizzard:

But with some styling magic you can create something like this for example:

Example styled with Tailwind and DaisyUI

The example above is created using this code:

<script setup lang="ts">
import { Stepper } from 'vue-stappen'
</script>

<template>
  <Stepper header-class="steps" step-class="border p-3 rounded-lg my-4 border-gray-200 dark:border-gray-700" v-bind="$props">
    <template #header-item="{ visited, step, active, processing, visit }">
      <li
        class="step" 
        :class="{
          'step-primary': visited,
          'step-secondary': visited && processing || step.processing,
          'step-accent font-bold text-black dark:text-white': active && !step.processing,
          'step-secondary font-bold text-black dark:text-white': active && step.processing,
        }"
        @click="visit()">
        {{ step.id }}
      </li>
    </template>

    <slot />

    <template #navigation="{ next, previous, previousStep, nextStep }">
      <div class="flex">
        <button v-if="previousStep" class="btn btn-neutral" @click="previous">Previous</button>
        <div class="w-full"></div>
        <button class="btn" :class="{ 'btn-neutral': nextStep, 'btn-primary': !nextStep }" @click="next">
          {{ nextStep ? 'Next' : 'Finish' }}
        </button>
      </div>
    </template>
  </Stepper>
</template>

Vue Stappen allows you to focus on the style of your stepper without writing stepper logic yourself. When "extending" the component like in the example above the only thing left to do is create steppers:

<script setup lang="ts">
import MyCustomStyleStepper from '@/components/MyCustomStyleStepper.vue'
import { Step } from 'vue-stappen'
</script>

<template>
  <MyCustomStyleStepper>
    <Step id="step1">
      Body step 1
    </Step>
    <Step id="step2">
      Body step 2
    </Step>
    <Step id="step3">
      Body step 3
    </Step>
  </MyCustomStyleStepper>
</template>

This library is designed to empower developers to create custom steppers with ease, providing a solid foundation for building intuitive and interactive user interfaces. In this guide, you will find comprehensive information on how to leverage our framework to craft your own unique stepper experiences. Let's dive in and start building!

Let's get started by creating a basic component and import the Stepper:

<!-- src/components/defaultStepper.vue -->

<script setup>
import { Stepper } from 'vue-stappen'
</script>

<template>
  <Stepper>
    <slot />
  </Stepper>
<template>

To style the header we can use a template for each item:

<template>
  <Stepper>
    <template #header-item="{ step }">
      <li @click="visit()">
        {{ step.id }}
      </li>
    </template>

    <slot />
  </Stepper>
<template>

I made sure to provide the header item with as much useful properties as possible aswell as the callbacks to allow for total controll. Keep in mind this template lives inside a loop which loops for each step the stepper can see.

As of now I made these props available:

The current callbacks are as follows:

These props and callbacks can be used to conditionally style your stepper. For example, if we want to highlight the current active step, we can do this:

<template #header-item="{ step, active, visited }">
  <li :class="{
    'text-red-500': active
  }" @click="visit()">
    {{ step.id }}
  </li>
</template>

If we want to highlight the visted steps:

<template #header-item="{ step, active, visited }">
  <li :class="{
    'text-red-500': active,
    'text-blue-500': visited,
  }" @click="visit()">
    {{ step.id }}
  </li>
</template>

If we want to take a "progressive" approach we can do this too. With "progressive" I mean highlighting all preceding steps and never subsequent steps even if they're visited to create a progressbar-like effect. Example:

<template #header-item="{ step, active, delta }">
  <li :class="{
    'text-red-500': active,
    'text-blue-500': delta <= 0, // Marks all preceding with blue
  }" @click="Math.abs(delta) === 1 ? visit() : null">
    {{ step.id }}
  </li>
</template>

Using the stepper is as easy as just importing the component and adding steps to it. The only mandatory prop for a step is it's id. The stepper will automatically detect these steps:

<script setup>
import Stepper from '@/components/progressiveStepper';
import { Step } from 'vue-stappen';
</script>

<template>
  <Stepper>
    <Step id="step1" custom-prop="You can use this value in the header by accesssing `step['custom-prop']`">
      Boddy of the step.
    </Step>
    <!-- Add as many as you want, as long as they have unique id's -->
  </Stepper>
</template>

I've added a guard system that allows you to prevent access to a step. You can add a global guard to the stepper component or add a single guard to a specific step. When both defined the global guard will be processed first, then the step guard defined on the step. Here is an example:

<script setup>
// Async exmaple
const globalGuard = async () => {
  return await new Promise((resolve, reject) => {
    resolve(true) // Allow move
    resolve(false) // Deny move
    reject('error') // Throw error
  })
}

// Basic conditional example
const stepGuard = () => {
  // Explicitily returnt `true` to allow move
  return true

  // Any thing else to deny the move
  return
  return false
}
</script>

<template>
  <Stepper :on-move="globalGuard">
    <Step :on-move="stepGuard">
      <!-- ... -->
    </Step>
  </Stepper>
</template>

There are 3 guards that are executed in the listed order:

These guards all receive the following parameters:

I appreciate any contributions. I'm still learning how to properly package things and I'm struggling with defining the types accurately. If you have suggestions for improvement or ideas on how things could be done better, please share them with me. Thank you!

pnpm install

pnpm dev

pnpm build

pnpm test:unit

pnpm lint