Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/glhd/alpine-wizard
Multi-step wizard helpers for Alpine.js
https://github.com/glhd/alpine-wizard
Last synced: 21 days ago
JSON representation
Multi-step wizard helpers for Alpine.js
- Host: GitHub
- URL: https://github.com/glhd/alpine-wizard
- Owner: glhd
- License: mit
- Created: 2022-06-15T13:51:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-08-15T17:01:51.000Z (over 1 year ago)
- Last Synced: 2024-11-02T18:41:34.252Z (about 1 month ago)
- Language: JavaScript
- Size: 33.2 KB
- Stars: 150
- Watchers: 6
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome - Alpine Wizard - Build multi-step wizards with Alpine.js
README
# Alpine Wizard
[](https://github.com/glhd/alpine-wizard/actions/workflows/tests.yml)
[](https://www.npmjs.com/package/@glhd/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](#installation)
- [Usage](#usage)
- [Using Validation Rules](#validation-rules)
- [API](#api)
## Installation
### via cdn
```html
```
### via npm
```shell
npm install @glhd/alpine-wizard
```
### via yarn
```shell
yarn add @glhd/alpine-wizard
```
## Usage
```html
Welcome! This step has no requirements, so we can continue
immediately. This is useful for things like introductions.
Your name:
Your age:
I have my parent or guardian's consent
Continue
Submit
```
[](https://codesandbox.io/s/zealous-sun-8xoswh?fontsize=14&hidenavigation=1&theme=dark)
## Validation Rules
The wizard also supports Laravel-style validation rules via the [`validatorjs`](https://github.com/mikeerickson/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):
```html
```
This plugin allows you to add a `.rules` modifier to steps:
```html
Your age:
```
See the [`validatorjs` documentation](https://github.com/mikeerickson/validatorjs) 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