Usage

Steps to use FormValidation

1. Uploading required files to the server

You need to upload the entire @form-validation folder to your server. The next steps assume that these folders are placed inside vendors/@form-validation.

2. Including necessary files

Add the library's CSS and JavaScript files to the head and right before the body tags:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <!-- Your form goes here -->
        ...
        <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>
    </body>
</html>

Since the library is written completely in ECMAScript 6 (ES 6), we need es6-shim.min.js to help the older browsers understand the modern features in ES6.

As mentioned in the previous section, the bundle/popular.min.js file provides the most popular validators. You have to replace it with the bundle/full.min.js file if you want to use all validators.

To reduce the page loading time:

Use the minified versions (.min.css and min.js files)
Insert the JavaScript files right before the body tag

3. Writing form and declaring validator rules

The library allows defining the validator for a field that is taken from the value of name attribute. The following snippet is a basic example of a logging-in form:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="loginForm" method="POST">
            <div>
                <label>Username</label>
                <input type="text" name="username" />
            </div>

            <div>
                <label>Password</label>
                <input type="password" name="password" />
            </div>

            <button type="submit">Submit</button>
        </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>
            document.addEventListener('DOMContentLoaded', function (e) {
                FormValidation.formValidation(document.getElementById('loginForm'), {
                    fields: {
                        username: {
                            validators: {
                                notEmpty: {
                                    message: 'The username is required',
                                },
                                stringLength: {
                                    min: 6,
                                    max: 30,
                                    message: 'The username must be more than 6 and less than 30 characters long',
                                },
                                regexp: {
                                    regexp: /^[a-zA-Z0-9_]+$/,
                                    message: 'The username can only consist of alphabetical, number and underscore',
                                },
                            },
                        },
                        password: {
                            validators: {
                                notEmpty: {
                                    message: 'The password is required',
                                },
                                stringLength: {
                                    min: 8,
                                    message: 'The password must have at least 8 characters',
                                },
                            },
                        },
                    },
                });
            });
        </script>
    </body>
</html>

As you can see, FormValidation.formValidation accepts two parameters:

The first parameter is the form element, which can be retrieved by the document.getElementById() method
The second parameter contains the options which is actually a JavaScript object. Its fields property maps the field name to the validator rules. The field name is defined by the name attribute, while the validator rules are defined by mapping the validator name to its options.

If the field name contains special characters such as ., [, ], you must wrap it between single or double quotes. See the special field name page

If the field doesn't have the name attribute, you can use a CSS selector to specify it

All validators provide a common option named message that will be used to inform the user if the associated field is invalid.

The options can be updated on the fly with the updateValidatorOption() method

You don't need to remember the options of any validator because you can refer to them on each validator page.

Here is what we have been following so far:

3. Writing form and declaring validator rules

Hey, I try to play with the form. Neither clicking the Submit button nor typing on the username or password field does perform any validations. That is the time to register plugins.

4. Adding plugins

FormValidation is developed on plugin-based architecture. Its solid, lightweight core library only implements needed methods and connects all plugins together. We need to enable some basic plugins to make the validation work.

In order to enable a particular plugin, you need to insert the plugin script (if required) and map a name with its instance in the plugins option:

<html>
    <head>
        <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>
        <!--
        Some additional plugins are not included in `bundle/popular(.min).js`.
        You have to insert it here after `bundle/popular(.min).js`
        -->
        <script src="/vendors/@form-validation/umd/plugins-[plugin-name-here]/index.min.js"></script>
        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('demoForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            pluginName: new FormValidation.plugins.PluginNameHere({
                                // The plugin options. Some plugins don't require any options
                                ...
                            }),
                            // Other plugins can be enabled here, of course
                            ...
                        },
                    }
                );
            });
        </script>
    </body>
</html>

We are going to enable some plugins to make the validations happen:

Plugin	Description
Message	Display error message that is defined in each validator options
Trigger	Indicate the events which the validation will be executed
SubmitButton	Automatically validate the form when pressing its Submit button
DefaultSubmit	Submit the form if all fields are valid after validating

Our demo page now looks like this:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="signinForm" 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>
        <!--
        The Message, Trigger, SubmitButton, and DefaultSubmit are core plugins. They are already included
        in `bundle/popular(.min).js`. Hence, you don't need to insert external plugin scripts here.
        -->
        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('signinForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            message: new FormValidation.plugins.Message({
                                clazz: '...',
                            }),
                            trigger: new FormValidation.plugins.Trigger(),
                            submitButton: new FormValidation.plugins.SubmitButton(),
                            defaultSubmit: new FormValidation.plugins.DefaultSubmit(),
                        },
                    }
                );
            });
        </script>
    </body>
</html>

Finally, you can try it in the following form to see how the validation works. Either click the Submit button or fill in the fields to see it in action.

4. Adding plugins

5. Using popular CSS frameworks

In the previous section, you learn how to use FormValidation with a native form. Nowadays, it's very common that you rely on a CSS framework to speed up development. FormValidation brings support for a lot of popular CSS frameworks.

Each of them is supported by a specific plugin that helps you minimize the integration parts such as automatically enabling the Message plugin, displaying the error messages at desired area instead of putting them at the bottom of the form, etc.

The following sample code is a starter page for using the Bootstrap plugin to validate a form made in the Bootstrap 4 framework:

<html>
    <head>
        <!-- FontAwesome is used to show the feedback icons -->
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" />

        <!-- Bootstrap CSS has to be inserted before FormValidation CSS -->
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.3.1/css/bootstrap.min.css" />
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="yourForm" 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>

        <!-- You need to insert the plugin that supports the CSS framework. It has to be inserted after `bundle/popular.min.js` -->
        <script src="/vendors/@form-validation/umd/plugin-bootstrap/index.min.js"></script>
        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('yourForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            trigger: new FormValidation.plugins.Trigger(),
                            submitButton: new FormValidation.plugins.SubmitButton(),
                            defaultSubmit: new FormValidation.plugins.DefaultSubmit(),
                            // Support the form made in Bootstrap 4
                            bootstrap: new FormValidation.plugins.Bootstrap(),
                            // Show the feedback icons taken from FontAwesome
                            icon: new FormValidation.plugins.Icon({
                                valid: 'fa fa-check',
                                invalid: 'fa fa-times',
                                validating: 'fa fa-refresh',
                            }),
                        },
                    }
                );
            });
        </script>
    </body>
</html>

You can see the sample code demonstrating the Bootstrap plugin in the following example:

5. Using with popular CSS frameworks

Refer to each plugin below if you want to get support for a particular CSS framework:

Overview Localization