Wizard plugin

Support validating multiple steps form

Usage

Assume that the form is split into multiple steps which can be accessed via a CSS class js-step. It also contains two buttons for jumping to the previous or next step.
<form id="demoForm" method="POST">
<!-- Split the form into multiple steps -->
<div class="js-step">...</div>
<div class="js-step">...</div>
<div class="js-step">...</div>
<!-- The button to go to the previous step -->
<button id="prevButton">Prev</button>
<!-- The button to go to the next step -->
<button id="nextButton">Next</button>
</form>
Clicking the Next button will validate the current step. If all fields in the step are valid, the plugin will bring user to the next step.
The following piece of code is the starting point to use the Wizard plugin:
<html>
<head>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/uikit/3.0.3/css/uikit.min.css" />
<link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
</head>
<body>
<form id="demoForm" method="POST">...</form>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
<script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
<script src="/vendors/@form-validation/umd/plugin-wizard/index.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function(e) {
FormValidation.formValidation(
document.getElementById('demoForm'),
{
fields: {
...
},
plugins: {
// The options here matches with the form above
wizard: new FormValidation.plugins.Wizard({
stepSelector: '.js-step',
prevButton: '#prevButton',
nextButton: '#nextButton',
}),
...
},
}
);
});
</script>
</body>
</html>

Options

The Wizard plugin provides the following options:
(* denotes a required parameter)
OptionTypeDescription
isFieldExcludedFunctionIndicate which fields should be execluded
isStepSkippedFunctionSkip a given step
nextButton *String or ElementA CSS selector of the Next button
prevButton *String or ElementA CSS selector of the Previous button
stepSelector *StringA CSS selector of steps
If you are using an id selector for the previous and next buttons, then they can be placed outside of the form as following:
<form>...</form>
<button id="prevButton">...</button>
<button id="nextButton">...</button>
You also can query the buttons and pass them to the options:
FormValidation.formValidation(form, {
plugins: {
wizard: new FormValidation.plugins.Wizard({
prevButton: document.getElementById('prevButton'),
nextButton: document.getElementById('nextButton'),
}),
},
});
Exclude a field
The isFieldExcluded option is a function that takes three parameters and returns true or false:
FormValidation.plugins.Wizard({
isFieldExcluded: function(field: string, element: HTMLElement, elements: HTMLElement[])
// field: The field name
// element: The field element
// elements: The field elements
// Returns `true` if you want to exclude the field, so it won't be validated
},
})
Skip a step
The isStepSkipped option is a function that takes skipStepProps parameter and returns true or false:
FormValidation.plugins.Wizard({
isStepSkipped: function (skipStepProps) {
// skipStepProps.currentStep: The current step
// skipStepProps.numSteps: The total number of steps
// skipStepProps.targetStep: The target step
// Returns `true` if you want to skip the step
},
});

Events

The Wizard plugin provides four events that you can trigger. The event handlers can be set via either plugin option
FormValidation.formValidation(form, {
fields: {
...
},
plugins: {
wizard: new FormValidation.plugins.Wizard({
// Triggered when a step is activated
onStepActive: function(e) {
// e.step is the zero-based index of current step
// e.numSteps is the number of steps
},
// Triggered when a step is invalid
onStepInvalid: function(e) {
// e.step is the zero-based index of current step
// e.numSteps is the number of steps
},
// Triggered when a step is valid
onStepValid: function(e) {
// e.step is the zero-based index of current step
// e.numSteps is the number of steps
},
// Triggered when all steps are valid
onValid: function(e) {
// e.numSteps is the number of steps
},
}),
},
});
or using on() as following:
FormValidation
.formValidation(form, {
fields: {
...
},
plugins: {
wizard: new FormValidation.plugins.Wizard({
stepSelector: '...',
prevButton: '...',
nextButton: '...',
}),
},
})
.on('plugins.wizard.step.active', function(e) {
// Same as onStepActive option
})
.on('plugins.wizard.step.invalid', function(e) {
// Same as onStepInvalid option
})
.on('plugins.wizard.step.valid', function(e) {
// Same as onStepValid option
})
.on('plugins.wizard.valid', function(e) {
// Same as onValid option
});

APIs

The plugin provides the following methods:
MethodDescription
goToNextStep()Jump to the next step. It's useful when users want to go to the next step automatically when a checkbox/radio button is chosen
goToPrevStep()Jump to the previous step
goToStep(index: number)Go to the given step
// Create a FormValidation instance
const fv = FormValidation.formValidation(form, {
fields: {
...
},
plugins: {
wizard: new FormValidation.plugins.Wizard(),
},
});
// Get the Wizard plugin instance
const wizardPlugin = fv.getPlugin('wizard');
// Call the API
wizardPlugin.goToNextStep();

Submitting form

You cannot use the DefaultSubmit plugin to submit the form when all steps are valid. Instead, you can use the onValid option (or listen the plugins.wizard.valid event):
FormValidation.formValidation(form, {
fields: {
...
},
plugins: {
wizard: new FormValidation.plugins.Wizard({
onValid: function(e) {
// Submit the form when all steps are valid
form.submit();
},
}),
},
});

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.
  • Install the packages:
$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-wizard
  • Import and use the Wizard plugin:
import { formValidation } from '@form-validation/bundle/popular';
import { Wizard } from '@form-validation/plugin-wizard';
formValidation(
document.getElementById('demoForm'),
{
fields: {
...
},
plugins: {
wizard: new Wizard({
...
}),
...
},
}
);

Basic example

Wizard plugin

Changelog

v2.4.0
v2.0.0
  • Add the npm package
v1.10.0
  • Add new goToStep() method
  • The previous and next buttons can be placed outside of the form by using the id selectors
v1.9.0
  • Allow to define the excluded field with the new isFieldExcluded option, so we can animate the current step when jumping between steps
  • Provide the ability of skipping a step via new isStepSkipped option
v1.6.0
  • Added new APIs to go to the previous or next steps
v1.5.0
  • Fixed a bug that the Wizard plugin doesn't work on IE 11
v1.3.0
  • First release. It means that the Wizard plugin requires FormValidation v1.3.0 or newer