Usage

Steps to use FormValidation

1. Uploading required files to server

You need to upload entire dist/css and dist/js folders to your server. The next steps assume that these folders are placed inside vendors/formvalidation.

2. Including necessary files

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




    


    
    ...
    



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

As mentioned in the previous section, FormValidation.min.js provides the most popular validators. You have to replaced it with FormValidation.full.min.js 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 to define the validator for field that is taken from the value of name attribute. The following snippet is a basic example of a logging in form:




    


    
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', }, } }, } } ); });

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.

Tip

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

Tip

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

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

Tip

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 in each validator page.

Here is what we have been following so far:

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, lighweight core libary only implements needed methods and connects all plugins together. We need to enable some basic plugins to make the validation works.

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:




    


    
...
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 ... }, } ); });

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. For example, perform validations whenever user focus on field and press any key.
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:




    


    
...
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(), }, } ); });

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

5. Using with 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 the development. FormValidation brings support for a lot of popular CSS frameworks. Each of them is supported by specific plugin which 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 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:




    
    

    
    
    


    
...
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', }), }, } ); });

Note

Bootstrap.min.js is the plugin provided by FormValidation. It is NOT the same as Bootstrap(.min).js file provided by Bootstrap framework.

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

Refer to each plugin from the table below if you want to get supports for particular CSS framework.

Plugin Supported CSS framework
Bootstrap Bootstrap v4.1.2
Bootstrap3 Boostrap v3.3.7
Bulma Bulma v0.7.1
Foundation Zurb Foundation v6.4.3
Materialize MaterializeCSS v1.0.0-rc.2
Milligram milligram v1.3.0
Mini mini.css v3.0.0
Mui MUI v0.9.39
Pure PureCSS v1.0.0
Semantic Semantic UI v2.3.3
Shoelace Shoelace v1.0.0-beta24
Spectre Spectre v0.5.3
Tachyons Tachyons v4.10.0
Turret turretcss v4.1.4
Uikit UIKit v3.0.0-rc.8