Composable

The useStepper composable provides methods to interact with and render your stepper. It can be used with or without the Scoped component.

Usage

<script setup lang="ts">
import { defineStepper } from "@stepperize/vue";
 
const { useStepper } = defineStepper(
  { id: "first" },
  { id: "second" },
  { id: "last" }
);
 
const stepper = useStepper();
</script>

Rendering Methods

when

The when method allows rendering content conditionally based on the current step. It can take an id of a step (either a string or an array of a step ID followed by booleans) and a whenFn (the function to execute if the step matches). Additionally, you can provide an optional elseFn (the function to execute if the step does not match).

<script setup lang="ts">
import { defineStepper, StepperWhen } from '@stepperize/vue'
 
const stepper = useStepper()
 
</script>
 
<template>
 
  <StepperWhen :stepper when="first">
    <template #default="step">
      <p>First step: {{ step.title }}</p>
    </template>
  </StepperWhen>
 
  <StepperWhen :stepper when="second">
    <template #default="step">
      <p>Second step: {{ step.title }}</p>
    </template>
  </StepperWhen>
 
  <StepperWhen :stepper when="last">
    <template #default>
      Finished!
    </template>
    <template #else>
      Not finished yet
    </template>
  </StepperWhen>
 
</template>

You can define more complex conditions that not only depend on the current step's ID but also on additional boolean values. This allows for multi-condition logic where each boolean must evaluate to true for the step to match. The boolean values can represent different state conditions or external factors that affect the step's visibility or behavior.

<script setup lang="ts">
import { defineStepper, StepperWhen } from '@stepperize/vue'
 
const stepper = useStepper()
 
const condition1 = ... // boolean
const condition2 = ... // boolean
 
</script>
 
<template>
 
  <StepperWhen :stepper :when="['first', condition1, condition2]">
    <template #default="step">
      <p>First step: {{ step.title }}</p>
    </template>
  </StepperWhen>
 
</template>

switch

The switch method allows you to render content based on the current step's ID, similar to a switch-case structure. This method provides a cleaner and more scalable way to handle different step-specific rendering logic, making it ideal for scenarios where you need to differentiate the UI depending on the current step without writing multiple when conditions.

<script setup lang="ts">
import { defineStepper, StepperSwitch } from '@stepperize/vue'
 
const stepper = useStepper()
 
</script>
 
<template>
 
  <StepperSwitch :stepper>
    <template #first="step">
      <p>First: {{ step.title }}</p>
    </template>
    <template #second="step">
      <p>Second: {{ step.title }}</p>
    </template>
    <template #last>
      Finished!
    </template>
  </StepperSwitch>
 
</template>

match

The match method allows you to render content based on an external state, such as a value fetched from a server or any dynamic state in your application. This provides flexibility for rendering content that is tied not only to the current step in the stepper but also to any other state outside the stepper's context, such as user actions, data from an API, or global application state.

<script setup lang="ts">
import { defineStepper, StepperMatch } from '@stepperize/vue'
 
const stepper = useStepper()
 
const state = "Value from server or client state"
 
</script>
 
<template>
 
  <StepperMatch :stepper :state>
    <template #first="step">
      <p>First: {{ step.title }}</p>
    </template>
    <template #second="step">
      <p>Second: {{ step.title }}</p>
    </template>
    <template #last>
      Finished!
    </template>
  </StepperMatch>
 
</template>

Before/after functions

While the API provides specific functions to move to the previous or next step, there are situations such as form validations where we want to execute actions before or after we move to the previous or next step.

That is why there are the following functions:

• beforeNext
• afterNext
• beforePrev
• afterPrev

beforeNext

The beforeNext function allows you to execute a function before moving to the next step. It returns a promise that resolves to a boolean value. If the promise resolves to true, the stepper will move to the next step. If the promise resolves to false, the stepper will not move to the next step.

In case you don't need a promise, you can use the beforeNext returning a boolean value.

afterNext

The afterNext function allows you to execute a function after moving to the next step. It returns a promise that resolves to a void value.

In case you don't need a promise, you can use the afterNext returning a void value.

beforePrev

The beforePrev function allows you to execute a function before moving to the previous step. It returns a promise that resolves to a boolean value. If the promise resolves to true, the stepper will move to the previous step. If the promise resolves to false, the stepper will not move to the previous step.

In case you don't need a promise, you can use the beforePrev returning a boolean value.

afterPrev

The afterPrev function allows you to execute a function after moving to the previous step. It returns a promise that resolves to a void value.

In case you don't need a promise, you can use the afterPrev returning a void value.

beforeGoTo

The beforeGoTo function allows you to execute a function before moving to a specific step. It returns a promise that resolves to a boolean value. If the promise resolves to true, the stepper will move to the specific step. If the promise resolves to false, the stepper will not move to the specific step.

<script setup lang="ts">
const stepper = useStepper();
</script>
<template>
  <button
    @click="() =>
      stepper.beforeGoTo('first', () => {
        // Your logic here
        return true; // or false
      })
    "
  >
    Go to first step
  </button>  
</template>

afterGoTo

The afterGoTo function allows you to execute a function after moving to a specific step. It returns a promise that resolves to a void value.

<script setup lang="ts">
const stepper = useStepper();
</script>
<template>
  <button
    @click="() =>
      stepper.afterGoTo('first', () => {
        // Your logic here
      })
    "
  >
    Go to first step
  </button>
</template>

Metadata

The metadata is a way to add custom data to a step. It is useful for adding dynamic values to a step, such as a value fetched from a server or any dynamic state in your application.

In order to add metadata to your stepper, you can add initial metadata in the useStepper composable.

const stepper = useStepper({
  initialMetadata: {
    first: {
      value: "1",
    },
  },
});

This metadata will be available in the metadata property of the useStepper composable and you can also use methods to set, get and reset the metadata.

setMetadata

Allows you to set the metadata for a step.

stepper.value.setMetadata("first", {
  value: "1",
});

getMetadata

The getMetadata method allows you to get the metadata for a step.

const metadata = stepper.value.getMetadata("first");

resetMetadata

The resetMetadata method allows you to reset the metadata for a step. You can also pass a boolean value to keep the initial metadata defined in the useStepper composable.

stepper.value.resetMetadata(true | false);

API Reference