vue-stappen

v1.3.3

Published

4 months ago

Vue 3 Stepper component

Downloads

0High
0Medium
0Low

timyourivh

vue vue3 vue 3 stepper component skeleton wizzard

Vue Stappen 🏎️

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

TODO list

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

Installation

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

Example

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>

Documentation / Setup guide

Creating your own component

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:

| Callback | The params it takes | What it does | | - | - | - | | visit() | - | Initiates an attempt to move to the current step |

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

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>

Guards

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:

Contributing

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!

Recommended IDE Setup

VSCode + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar).

Type Support for `.vue` Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need TypeScript Vue Plugin (Volar) to make the TypeScript language service aware of .vue types.

If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a Take Over Mode that is more performant. You can enable it by the following steps:

Disable the built-in TypeScript Extension
1. Run Extensions: Show Built-in Extensions from VSCode's command palette
2. Find TypeScript and JavaScript Language Features, right click and select Disable (Workspace)
Reload the VSCode window by running Developer: Reload Window from the command palette.

Customize configuration

See Vite Configuration Reference.

Project Setup

pnpm install

Compile and Hot-Reload for Development

pnpm dev

Type-Check, Compile and Minify for Production

pnpm build

Run Unit Tests with Vitest

pnpm test:unit

Lint with ESLint

pnpm lint