Home

Awesome

Alpine Wizard

Tests npm version

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).

x-wizard-github

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>

Try it out

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:

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