@glhd/alpine-wizard

Alpine Wizard

This package provides an Alpine directive (x-wizard) and a magic helper ($wizard) that allow you to quickly build multi-step wizards using Alpine.js (only 1.1 kB gzipped).

• Installation
• Usage
• Using Validation Rules
• API

Installation

via cdn

<script defer src="https://unpkg.com/@glhd/alpine-wizard@1/dist/wizard.cdn.min.js"></script>
<script defer src="https://unpkg.com/alpinejs@3/dist/cdn.min.js"></script>

via npm

npm install @glhd/alpine-wizard

via yarn

yarn add @glhd/alpine-wizard

Usage

<!-- This is the data our wizard will work with. It's just plain Alpine. -->
<form x-data="{ name: '', age: 0, coppa: false }">
    
    <!-- Add steps with x-wizard:step -->
    <div x-wizard:step>
        Welcome! This step has no requirements, so we can continue
        immediately. This is useful for things like introductions.
    </div>
    
    <!-- Steps can have logic about when they're complete. In this -->
    <!-- case, you must have entered a value for "name" to continue. -->
    <div x-wizard:step="name.trim() !== ''">
        Your name: <input x-model="name" name="name" />
    </div>
	
    <!-- Here's another step that has logic about when it's complete -->
	<div x-wizard:step="age > 0">
		Your age: <input x-model="age" name="age" />
	</div>
	
    <!-- Steps can also have logic about when they apply. In this -->
    <!-- case, this step is only shown if the person is under 13. -->
	<div x-wizard:if="age < 13" x-wizard:step="coppa === true">
		<label>
			<input type="checkbox" x-model="coppa" />
			I have my parent or guardian's consent
		</label>
    </div>
	
    <!-- We also expose a $wizard magic that gives lots of helper -->
    <!-- functionality. Here we have the logic for a continue button -->
	<button
		@click="$wizard.forward()"
		:disabled="$wizard.cannotGoForward()"
		x-show="$wizard.isNotLast()"
	>
        Continue
    </button>
	
    <!-- And here's a "submit" button when they get to the end. -->
	<button
		:disabled="$wizard.isNotComplete()"
		x-show="$wizard.isLast()"
	>
        Submit
    </button>
    
</form>

Validation Rules

The wizard also supports Laravel-style validation rules via the validatorjs package. If you're using the CDN version of the script, be sure to add the Validator package to the page before the wizard plugin (if you're installing via npm or yarn this functionality is available by default):

<script defer src="https://unpkg.com/validatorjs@3/src/validator.js"></script>

This plugin allows you to add a .rules modifier to steps:

<div x-wizard:step.rules="{ age: 'required|numeric|min:1|max:120' }">
    Your age: <input x-model="age" name="age" />
</div>

See the validatorjs documentation for a list of all supported rules and how to configure them.

API

Alpine Directives

x-wizard:step

Use x-wizard:step to define each wizard step. This directive optionally accepts a javascript expression which must return a truthy value before the step is considered complete.

x-wizard:if

Use x-wizard:if to make a step conditional. Any steps that have x-wizard:if will only show if the expression passed to the directive returns a truthy value.

x-wizard:title

Use x-wizard:title to set the step title. This is useful if you want to present the title of the current step elsewhere in your UI. By default, this is just a plain string, but you can generate the title dynamically by using the .dynamic modifier.

Alpine Magics

$wizard

The $wizard magic provides access to the state of your current wizard. It provides a number of useful helper functions:

• current() — get the current wizard step
• next() — get the next wizard step (or null if at end)
• previous() — get the previous wizard step (or null if at beginning)
• progress() — get current progress, a JS object:
  • current — the current step number (as of 1.2.0)
  • total — the total number of applicable steps
  • complete — the number of completed steps
  • incomplete — the number of steps still to complete
  • percentage — the percent complete, as a string (i.e. "33%")
  • percentage_int — the percent complete, as an integer (i.e. 33) (as of 1.2.0)
  • percentage_float — the percent complete, as an float (i.e. 0.33) (as of 1.2.0)
• isFirst() — check if we're currently on the first step
• isNotFirst() — check if we're NOT currently on the first step
• isLast() — check if we're on the last step
• isNotLast() — check if we're NOT on the last step
• isComplete() — check if we're on the last step and all steps are complete
• isNotComplete()/isIncomplete() — check if we're not on the last step or all steps aren't complete
• canGoForward() — check if we can move to the next step
• cannotGoForward() — check if we CANNOT move to the next step
• forward() — move to the next step if possible
• canGoBack() — check if we can go to the previous step
• cannotGoBack() — check if we CANNOT go to the previous step
• back() — move to the previous step if possible

Each step is a plain javascript object with a few properties:

• el — the DOM element associated with the step
• title — the title of the step
• is_applicable — whether this step applies given the current data
• is_complete — whether this step is complete