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)

Option	Type	Description
`isFieldExcluded`	`Function`	Indicate which fields should be execluded
`isStepSkipped`	`Function`	Skip a given step
`nextButton` *	`String` or `Element`	A CSS selector of the Next button
`prevButton` *	`String` or `Element`	A CSS selector of the Previous button
`stepSelector` *	`String`	A 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:

Method	Description
`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

The plugin can be enabled or disabled using the enablePlugin and disablePlugin methods

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

Uikit plugin API