This site contains the document for old version. Please upgrade to the latest version v1.0.0

Settings

Settings structure

There are three levels of settings which are form, field, and validators.

The FormValidation plugin can be called as following:

$(formSelector).formValidation({
    // Indicate the framework
    // It can be: bootstrap, bootstrap4, foundation5, foundation, pure, semantic, uikit
    framework: 'bootstrap',

    // ... Form settings go here ...
    fields: {
        fieldName: {
            // ... Field settings go here ...

            validators: {
                specificValidatorName: {
                    // ... common validator settings go here ...

                    // ... specific validator settings ...
                }
            }
        }
    }
});
If the field name contains special characters such as ., [, ], you must wrap it between single or double quote. See the Validating field with special name example

Most of settings can be set via HTML 5 attributes prefixed with data-fv.

For example, the following call:

$(formSelector).formValidation({
    framework: 'bootstrap',
    excluded: [':disabled', ':hidden', ':not(:visible)'],
    icon: {
        valid: 'glyphicon glyphicon-ok',
        invalid: 'glyphicon glyphicon-remove',
        validating: 'glyphicon glyphicon-refresh'
    },
    live: 'enabled',
    message: 'This value is not valid',
    trigger: null,
    fields: ...
});

is equivalent with the one below:

<form
    data-fv-framework="bootstrap"
    data-fv-message="This value is not valid"
    data-fv-icon-valid="glyphicon glyphicon-ok"
    data-fv-icon-invalid="glyphicon glyphicon-remove"
    data-fv-icon-validating="glyphicon glyphicon-refresh"
    data-fv-live="enabled">
    ...
</form>

<script>
$(document).ready(function() {
    $(formSelector).formValidation({
        fields: ...
    });
});
</script>
The Setting validator options via HTML attributes example shows how to use the declarative code in action.

In the next sections, you will see the full list of options for each level.

Form settings

Below is the list of settings for form sorted in alphabetical order:

Option Equivalent HTML attribute Default
autoFocus data-fv-autofocus true
button
  • data-fv-button-selector
  • data-fv-button-disabled
 
button: {
    selector: '[type="submit"]',
    disabled: ''
}
err
  • data-fv-err-clazz
  • data-fv-err-container
 
err: {
    clazz: '',
    container: null
}
excluded data-fv-excluded [':disabled', ':hidden', ':not(:visible)']
framework data-fv-framework bootstrap
icon
  • data-fv-icon-valid
  • data-fv-icon-invalid
  • data-fv-icon-validating
 
{
    valid: null,
    invalid: null,
    validating: null
}
live data-fv-live 'enabled'
message data-fv-message 'This value is not valid'
row
  • data-row-selector
  • data-row-valid
  • data-row-invalid
 
row: {
    selector: null,
    valid: '',
    invalid: ''
}
threshold data-fv-threshold null
trigger data-fv-trigger null
verbose data-fv-verbose true
fields n/a null

autoFocus

autoFocus: Boolean — Indicate the first invalid field will be focused on automatically. It is true, by default.

You also can set this option for particular field.

button

button: {
    // The submit buttons selector
    selector: '[type="submit"]:not([formnovalidate])',

    // The disabled class
    disabled: ''
}

selector

selector: String — The CSS selector indicates the submit buttons.

Clicking on these buttons will validate the form. They will be disabled when the form input are invalid to prevent the valid form from multiple submissions.

disabled

disabled: String — The CSS class for disabled button. The default value is defined by specific frameworks as following:

Framework Disabled button class
Bootstrap disabled
Foundation disabled
Pure pure-button-disabled
Semantic disabled
UIKit disabled
Example

err

err: {
    // The CSS class of each message element
    clazz: '',

    // The error messages container
    container: null
}

clazz

clazz: String — The CSS class of message element. The default value is taken from specific framework if available:

Framework err.clazz default value
Bootstrap 3 help-block
Bootstrap 4 text-help
Foundation 5 error
Foundation 6 form-error
Pure fv-help-block
Semantic ui red pointing label
UIKit uk-text-danger

container

container: String|Function — Indicate where the error messages are shown. It is null by default.

Value Description
CSS selector All error messages are placed in element defined by this CSS selector
A callback

A callback returns the element that the messages are placed in:

function($field, validator) {
    // $field is the field element
    // validator is the plugin instance
};
tooltip Error messages of each field are placed inside a tooltip
popover Error messages of each field are placed inside a popup

The tooltip or popover is provided by specific framework:

Framework Tooltip Popover
Bootstrap Bootstrap's tooltip Bootstrap's popover
Foundation Foundation's tooltip
Pure n/a
Semantic Semantic's popup
UIKit UIKit's tooltip
If you want to use a custom tooltip library, please take a look at the Using hint library or Using Balloon CSS library examples.

This option can be overridden by particular field.

Examples

The following form uses Bootstrap tooltip to show the error message.

<form id="containerForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Full name</label>
        <div class="col-xs-4">
            <input type="text" class="form-control" name="firstName" placeholder="First name" />
        </div>
        <div class="col-xs-4">
            <input type="text" class="form-control" name="lastName" placeholder="Last name" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Phone number</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="phone" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-9 col-xs-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#containerForm').formValidation({
        framework: 'bootstrap',
        err: {
            container: 'tooltip'
        },
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            firstName: {
                validators: {
                    notEmpty: {
                        message: 'The first name is required'
                    }
                }
            },
            lastName: {
                validators: {
                    notEmpty: {
                        message: 'The last name is required'
                    }
                }
            },
            phone: {
                validators: {
                    digits: {
                        message: 'The phone number can contain digits only'
                    },
                    notEmpty: {
                        message: 'The phone number is required'
                    }
                }
            }
        }
    });
});
</script>

excluded

excluded: String|String[]|Function — Indicate fields which won't be validated.

By default, the plugin will not validate the following kind of fields:

  • disabled
  • hidden
  • invisible

The setting consists of jQuery filters. Accept 3 formats:

Format Description
String

Filters are separated by a comma. For example:

':disabled, :hidden, :not(:visible)'
Array of strings

Each element is a filter. For example:

[':disabled', ':hidden', ':not(:visible)']
Array of strings and callback functions

The callback function has format as below:

function($field, validator) {
    // $field is jQuery object representing the field element
    // validator is the plugin instance
    // return true or false;
}

For example:

[':disabled', ':hidden', function($field, validator) {
    // Do not validate invisible element
    return !$field.is(':visible');
}]

It is also possible to excluded particular field.

The excluded option is usually used when we need to validate the field generated by other UI plugin. For an usage, you can take a look at compatibility examples.

framework

framework: String — Indicate the framework you are using.

It can be one of following values:

Value Framework Latest supported version
bootstrap default Bootstrap 3 3.3.7
bootstrap4 Bootstrap 4 4.0.0 alpha 3
foundation5 Foundation 5 5.5.3
foundation Foundation 6 6.2.3
pure Pure 0.6.0
semantic Semantic UI 2.2.2
uikit UIKit 2.26.4
FormValidation is designed to work with other frameworks. Take a look at the Supporting other frameworks and form builders section to see how it can be done

icon

Indicate valid/invalid/validating icons based on the field validity.

icon: {
    valid: null,
    invalid: null,
    validating: null
}

By default, these icons are not set. You also can enabled or disable feedback icon for particular field.

The Showing required icon example and mandatoryIcon add-on are useful when you want to display the mandatory icon for required fields
  • When using Bootstrap framework, ensure that you are using Bootstrap v3.1.0 or later
  • When using Semantic framework, wrap the field inside
<div class="ui input icon"></div>

You can use icons provided by

Icon sets Example
Glyphicons 
icon: {
    valid: 'glyphicon glyphicon-ok',
    invalid: 'glyphicon glyphicon-remove',
    validating: 'glyphicon glyphicon-refresh'
}
FontAwesome 
icon: {
    valid: 'fa fa-check',
    invalid: 'fa fa-times',
    validating: 'fa fa-refresh'
}

There is a FontAwesome issue (#41313) that causes the icon to be aligned not properly when using with Bootstrap. While waiting for this issue to be fixed, you can resolve it by placing the FontAwesome CSS before Bootstrap CSS:

<!-- Load FontAwesome CSS before Bootstrap -->
<link rel="stylesheet" href="/vendor/font-awesome/css/font-awesome.min.css" />
<link rel="stylesheet" href="/vendor/bootstrap/css/bootstrap.min.css"/>
Semantic icons 
icon: {
    valid: 'checkmark icon',
    invalid: 'remove icon',
    validating: 'refresh icon'
}
UIKit

UIKit uses the FontAwesome icons, but replaces the fa fa-xxx class with uk-icon-xxx one.

icon: {
    valid: 'uk-icon-check',
    invalid: 'uk-icon-times',
    validating: 'uk-icon-refresh'
}
This example shows how to use the icons provided by Google material design icons
Using with Bootswatch

Some BootsWatch themes override some CSS styles causing feedback icon invisible to your eyes. For instance, the Flatly theme set the feedback icon color to #FFF.

To fix this, you can simply add some CSS to your head, right before the BootsWatch theme CSS, to reset the feedback icons color:

<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootswatch/3.1.1/flatly/bootstrap.min.css">
<style type="text/css">
.has-error .form-control-feedback {
    color: #E74C3C;
}
.has-success .form-control-feedback {
    color: #18BCA0;
}
</style>
Example

live

live: String — Live validating mode. Can be one of three values:

Value Description
enabled default The plugin validates fields as soon as they are changed
disabled Disable the live validating. The error messages are only shown after the form is submitted
submitted The live validating is enabled after the form is submitted

There is no live option for particular field. If you don't want the field to be validated as soon as you change its value, you can use the trigger and threshold options.

message

message: String — The default error message for all fields. You can specify the error message for any fields or validators.

This example gives you an idea how to display custom messages returned from the server

row

row: {
    selector: null,
    valid: '',
    invalid: ''
}

selector

selector: String — CSS selector indicates the parent element of field. Each framework usually wraps both field and its label inside elements with the same CSS class

The default value of this option is defined by specific framework:

Framework row.selector default value
Bootstrap .form-group
Foundation .row
Pure .pure-control-group
Semantic fields
UIKit .uk-form-row

This option might be used in the following cases:

  • The form uses a custom CSS class for each group
  • Each group consist of more than one field

You also can specify the row for particular field.

Example

In the following form, each field is placed inside a cell of table. The error messages are placed inside a tooltip.

<style type="text/css">
#groupForm i.form-control-feedback {
    top: 5px !important;
    right: 5px;
}
</style>

<p>We would like to know 5 recent projects you have done:</p>
<form id="groupForm">
    <div class="table-responsive">
        <table class="table table-bordered table-striped">
            <thead>
                <tr>
                    <th>Project</th>
                    <th>Role</th>
                    <th>URL</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td><input type="text" class="form-control" name="project[]" /></td>
                    <td><input type="text" class="form-control" name="role[]" /></td>
                    <td><input type="text" class="form-control" name="url[]" /></td>
                </tr>
                <tr>
                    <td><input type="text" class="form-control" name="project[]" /></td>
                    <td><input type="text" class="form-control" name="role[]" /></td>
                    <td><input type="text" class="form-control" name="url[]" /></td>
                </tr>
                <tr>
                    <td><input type="text" class="form-control" name="project[]" /></td>
                    <td><input type="text" class="form-control" name="role[]" /></td>
                    <td><input type="text" class="form-control" name="url[]" /></td>
                </tr>
                <tr>
                    <td><input type="text" class="form-control" name="project[]" /></td>
                    <td><input type="text" class="form-control" name="role[]" /></td>
                    <td><input type="text" class="form-control" name="url[]" /></td>
                </tr>
                <tr>
                    <td><input type="text" class="form-control" name="project[]" /></td>
                    <td><input type="text" class="form-control" name="role[]" /></td>
                    <td><input type="text" class="form-control" name="url[]" /></td>
                </tr>
            </tbody>
        </table>
    </div>

    <button type="submit" class="btn btn-default">Validate</button>
</form>

<script>
$(document).ready(function() {
    $('#groupForm').formValidation({
        framework: 'bootstrap',
        err: {
            container: 'tooltip'
        },
        row: {
            selector: 'td'
        },
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            'project[]': {
                validators: {
                    notEmpty: {
                        message: 'The project name is required'
                    }
                }
            },
            'role[]': {
                validators: {
                    notEmpty: {
                        message: 'The role is required'
                    }
                }
            },
            'url[]': {
                validators: {
                    notEmpty: {
                        message: 'The URL is required'
                    },
                    uri: {
                        message: 'The URL is invalid'
                    }
                }
            }
        }
    });
});
</script>

valid

valid: String — The CSS class for success row that contains valid field

invalid

invalid: String — The CSS class for error row that contains invalid field

The default values of valid and invalid options are defined as following:

Framework row.valid default value row.invalid default value
Bootstrap has-success has-error
Foundation fv-has-success error
Pure fv-has-success fv-has-error
Semantic fv-has-success error
UIKit fv-has-success fv-has-error

Adding custom class to field container while it is being validated

There's no built-in option like row.validating but it's possible to add a custom class to the field container while validating it.

To archive it, you can trigger the status.field.fv event. The following code snippet demonstrates how to do it while the field is being validated by the remote validator:

$(form)
    .formValidation({
        framework: 'bootstrap',
        fields: {
            // You might need to change username to your field name
            username: {
                validators: {
                    remote: {
                        type: 'POST',
                        url: '/path/to/your/api/',
                        message: 'The username is not available'
                    }
                }
            }
        }
    })
    .on('status.field.fv', function(e, data) {
        // data.field is the field name
        // data.status is the current status of validator
        // data.element is the field element

        if (data.field === 'username') {
            // Assume that the form uses the Bootstrap framework
            // and has a standard structure
            // Each pair of field and label are placed inside a .form-group element

            // Determine the field container
            var $container = data.element.closest('.form-group');

            (data.status === 'VALIDATING')
                ? $container.addClass('custom-class')
                : $container.removeClass('custom-class');
        }
    });
If you want get more attention from user while the field is being validated, take a look at this example
Example

threshold

threshold: Number — The field will not be live validated if its length is less than this number of characters. You also can set this option for particular field.

trigger

trigger: String — The event which is fired to validating all fields when the live validating mode is enabled. If you need multiple events are fired, then separate them by a space.

It's also possible to set trigger option for each field. Look at the field trigger section.

verbose

verbose: Boolean — Whether to be verbose when validating a field or not.

Value Description
true When a field has multiple validators, all of them will be checked respectively. If errors occur in multiple validators, all of them will be displayed to the user
false when a field has multiple validators, validation for this field will be terminated upon the first encountered error. Thus, only the very first error message related to this field will be displayed to the user

It's also possible to set verbose option for each field. Look at the field verbose section.

Field settings

Below is the list of Field settings:

Option Equivalent HTML attribute
autoFocus data-fv-autofocus
enabled data-fv-enabled
err data-fv-err
excluded data-fv-excluded
icon data-fv-icon
message data-fv-message
row data-fv-row
selector data-fv-selector
threshold data-fv-threshold
trigger data-fv-trigger
verbose data-fv-verbose

autoFocus

autoFocus: Boolean — Indicate the field will be focused on automatically if it is not valid. It is true, by default.

In some case, you don't want the invalid field to be focused automatically. For example, focusing on a field using a date picker might show up the picker, which seems to be annoyed.

enabled

enabled: Boolean — Enable or disable the field validators.

If you want to enable or disable particular validator, use validator's enabled option or enableFieldValidators() method.

Example

err

err: String|Function — Indicate where the error messages are shown.

Value Description
CSS selector Error messages are placed in element defined by this CSS selector
A callback

A callback returns the element that the messages are placed in:

function($field, validator) {
    // $field is the field element
    // validator is the plugin instance
};
tooltip Error messages are placed inside a tooltip.
popover Error messages are placed inside a popover.
Example

The following form illustrates an usage of the err option. The error messages are shown in the element defined by a CSS selector.

<form id="profileForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Full name</label>

        <div class="col-xs-4">
            <input type="text" class="form-control" name="firstName" placeholder="First name" />
            <span class="help-block" id="firstNameMessage"></span>
        </div>

        <div class="col-xs-4">
            <input type="text" class="form-control" name="lastName" placeholder="Last name" />
            <span class="help-block lastNameMessage"></span>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Username</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#profileForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            firstName: {
                err: '#firstNameMessage',
                validators: {
                    notEmpty: {
                        message: 'The first name is required and cannot be empty'
                    }
                }
            },
            lastName: {
                err: '.lastNameMessage',
                validators: {
                    notEmpty: {
                        message: 'The last name is required and cannot be empty'
                    }
                }
            },
            username: {
                message: 'The username is not valid',
                validators: {
                    notEmpty: {
                        message: 'The username is required and cannot be empty'
                    },
                    stringLength: {
                        min: 6,
                        max: 30,
                        message: 'The username must be more than 6 and less than 30 characters long'
                    }
                }
            }
        }
    });
});
</script>

excluded

excluded: Boolean|Function — Indicate whether or not the field is excluded.

To exclude a set of fields, you should use the excluded option for form.

// Use Boolean value
excluded: true or false

// Use the return value of a callback function
excluded: function($field, validator) {
    // $field is the field element
    // validator is the plugin instance
    return true;    // or false
}
Example

icon

icon: Boolean — Enable or disable feedback icons.

Example

The form below disables the feedback icons for field by setting icon: false or icon: 'false'

<form id="profileForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Address</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="address" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">City</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="city" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Phone number</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="phone" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-5 col-xs-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#profileForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            address: {
                icon: 'false',
                validators: {
                    notEmpty: {
                        message: 'The address is required and cannot be empty'
                    }
                }
            },
            city: {
                icon: false,
                validators: {
                    notEmpty: {
                        message: 'The city is required and cannot be empty'
                    }
                }
            },
            phone: {
                icon: true,
                validators: {
                    notEmpty: {
                        message: 'The phone number is required and cannot be empty'
                    },
                    phone: {
                        country: 'US',
                        message: 'The phone number is not valid'
                    }
                }
            }
        }
    });
});
</script>

message

message: String — The default error message for the field.

row

row: String — CSS selector indicates the parent element of field

You can set the same selector for all fields in form by applying the row.selector option for form.

selector

selector: String — The CSS selector to indicate the field. It is used in case that it's not possible to use the name attribute for the field.

When using the selector option, ensure that the field doesn't use some HTML 5 attributes (such as required, maxlength, etc.) that enables validators automatically
Example

Instead of using the name attribute, the following form uses the selector option to define the fields:

<form id="paymentForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Credit card number</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" id="ccNumber" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Expiration</label>
        <div class="col-xs-3">
            <input type="text" class="form-control" placeholder="Month" data-stripe="exp-month" />
        </div>
        <div class="col-xs-3">
            <input type="text" class="form-control" placeholder="Year" data-stripe="exp-year" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">CVV</label>
        <div class="col-xs-2">
            <input type="text" class="form-control cvvNumber" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#paymentForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            ccNumber: {
                selector: '#ccNumber',
                validators: {
                    notEmpty: {
                        message: 'The credit card number is required'
                    },
                    creditCard: {
                        message: 'The credit card number is not valid'
                    }
                }
            },
            expMonth: {
                selector: '[data-stripe="exp-month"]',
                row: '.col-xs-3',
                validators: {
                    notEmpty: {
                        message: 'The expiration month is required'
                    },
                    digits: {
                        message: 'The expiration month can contain digits only'
                    },
                    callback: {
                        message: 'Expired',
                        callback: function(value, validator) {
                            value = parseInt(value, 10);
                            var year         = validator.getFieldElements('expYear').val(),
                                currentMonth = new Date().getMonth() + 1,
                                currentYear  = new Date().getFullYear();
                            if (value < 0 || value > 12) {
                                return false;
                            }
                            if (year == '') {
                                return true;
                            }
                            year = parseInt(year, 10);
                            if (year > currentYear || (year == currentYear && value >= currentMonth)) {
                                validator.updateStatus('expYear', 'VALID');
                                return true;
                            } else {
                                return false;
                            }
                        }
                    }
                }
            },
            expYear: {
                selector: '[data-stripe="exp-year"]',
                row: '.col-xs-3',
                validators: {
                    notEmpty: {
                        message: 'The expiration year is required'
                    },
                    digits: {
                        message: 'The expiration year can contain digits only'
                    },
                    callback: {
                        message: 'Expired',
                        callback: function(value, validator) {
                            value = parseInt(value, 10);
                            var month        = validator.getFieldElements('expMonth').val(),
                                currentMonth = new Date().getMonth() + 1,
                                currentYear  = new Date().getFullYear();
                            if (value < currentYear || value > currentYear + 100) {
                                return false;
                            }
                            if (month == '') {
                                return false;
                            }
                            month = parseInt(month, 10);
                            if (value > currentYear || (value == currentYear && month >= currentMonth)) {
                                validator.updateStatus('expMonth', 'VALID');
                                return true;
                            } else {
                                return false;
                            }
                        }
                    }
                }
            },
            cvvNumber: {
                selector: '.cvvNumber',
                validators: {
                    notEmpty: {
                        message: 'The CVV number is required'
                    },
                    cvv: {
                        message: 'The value is not a valid CVV',
                        creditCardField: 'ccNumber'
                    }
                }
            }
        }
    });
});
</script>

As you see, the field can be defined by a ID (#ccNumber), class (.cvvNumber) or attribute ([data-stripe="exp-month"]) selector.

threshold

threshold: Number — Do not live validate field until the length of field value exceed this number.

Example
<form id="thresholdForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Full name</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="fullname" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Gender</label>
        <div class="col-xs-5">
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="male" /> Male
                </label>
            </div>
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="female" /> Female
                </label>
            </div>
            <div class="radio">
                <label>
                    <input type="radio" name="gender" value="other" /> Other
                </label>
            </div>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Phone number</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="phone" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Address</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="address" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-9 col-xs-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#thresholdForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        threshold: 3,
        fields: {
            fullname: {
                threshold: 10,
                validators: {
                    notEmpty: {
                        message: 'The full name is required'
                    }
                }
            },
            gender: {
                // The threshold option does not effect to the elements which user cannot type, such as radio, checkbox, select one
                threshold: 5,
                validators: {
                    notEmpty: {
                        message: 'The summary is required'
                    }
                }
            },
            phone: {
                threshold: 5,
                validators: {
                    notEmpty: {
                        message: 'The phone number is required'
                    },
                    phone: {
                        message: 'The phone number is not valid',
                        country: 'US'
                    }
                }
            },
            address: {
                // The threshold option is not set, it will be taken from the form option (which is 3 in this example)
                validators: {
                    notEmpty: {
                        message: 'The city is required'
                    }
                }
            }
        }
    });
});
</script>

trigger

trigger: String — The field events (separated by a space) which are fired when the live validating mode is enabled.

For example, trigger="focus blur" means that the field will be validated when user focus on or leave the focus off the field.

Example

In the following form, the Title field will be validated while user type any character (trigger="keyup"). The Summary field will be validated when user lose the focus (trigger="blur").

<form id="articleForm" method="post" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Title</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="title" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Summary</label>
        <div class="col-xs-5">
            <textarea rows="5" class="form-control" name="summary"></textarea>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Description</label>
        <div class="col-xs-9">
            <textarea rows="10" class="form-control" name="description"></textarea>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#articleForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            title: {
                trigger: 'keyup',
                validators: {
                    notEmpty: {
                        message: 'The title is required'
                    }
                }
            },
            summary: {
                trigger: 'blur',
                validators: {
                    notEmpty: {
                        message: 'The summary is required'
                    }
                }
            },
            description: {
                validators: {
                    notEmpty: {
                        message: 'The description is required'
                    }
                }
            }
        }
    });
});
</script>

verbose

verbose: Boolean — Whether to be verbose when validating a field or not.

Look at the form verbose section to see the possible value for the verbose option.

Validator settings

The following table shows the common settings for validators (when using it, replace {validatorname} with the validator name). For specific settings of each validator, please look at its documentation.

Option Equivalent HTML attribute
enabled data-fv-{validatorname}
message data-fv-{validatorname}-message
transformer n/a

enabled

enabled: Boolean — Indicate the validator is enabled or disabled. It is true, by default.

Look at the field's enabled option if you want to enable/disable all validators.

The table below shows three equivalent ways to enable or disable given validator:

Usage Example
HTML 5 attribute 
<!-- Enable validator -->
<input class="form-control" name="fullName" data-fv-notempty />

<!-- or -->
<input class="form-control" name="fullName" data-fv-notempty="true" />

<!-- Disable validator -->
<input class="form-control" name="fullName" data-fv-notempty="false" />
Plugin option 
$(document).ready(function() {
    $(form).formValidation({
        fields: {
            fullName: {
                validators: {
                    notEmpty: {
                        enabled: true   // or false
                    }
                }
            }
        }
    });
});
enableFieldValidators() 
// Enable validator
$(form)
    .formValidation('enableFieldValidators', fullName, true, 'notEmpty');

// Disable validator
$(form)
    .formValidation('enableFieldValidators', fullName, false, 'notEmpty');
Examples
<form id="validatorEnabledForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Full name</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="fullName" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-5 col-xs-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#validatorEnabledForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            fullName: {
                validators: {
                    notEmpty: {
                        // enabled is true, by default
                        message: 'The full name is required and cannot be empty'
                    },
                    stringLength: {
                        enabled: true,
                        min: 8,
                        max: 40,
                        message: 'The full name must be more than 8 and less than 40 characters long'
                    },
                    regexp: {
                        enabled: false,
                        regexp: /^[a-zA-Z\s]+$/,
                        message: 'The full name can only consist of alphabetical, number, and space'
                    }
                }
            }
        }
    });
});
</script>

message

message: String — The error message of validator for field.

message can be updated on the fly via the updateMessage() method

transformer

transformer: Function — Modify the field value before validating.

transformer: function($field, validatorName, validator) {
    // $field is the jQuery object presenting the field element
    // validatorName is the name of current validator
    // validator is the instance of plugin

    // You can get the field value
    var value = $field.val();

    // Modify it
    // ...

    // ... and return
    return value;
}
FormValidation only uses the value returned by the transformer option for validating. It does NOT send the modified value to the server when submitting the form
Example

The following form accepts a website address without http:// or https:// prefix.

By default, these kind of URLs don't pass the uri validators. Applying the transformer option for the uri validator, we can make it pass.

<form id="profileForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Website</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="website" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#profileForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            website: {
                validators: {
                    uri: {
                        message: 'The website address is not valid',
                        transformer: function($field, validatorName, validator) {
                            // Get the field value
                            var value = $field.val();

                            // Check if it doesn't start with http:// or https://
                            if (value && value.substr(0, 7) !== 'http://' && value.substr(0, 8) !== 'https://') {
                                // then prefix with http://
                                value = 'http://' + value;
                            }

                            // Return new value
                            return value;
                        }
                    }
                }
            }
        }
    });
});
</script>

Dynamic option

Some validators have option which its value could be change dynamically.

For example, the zipCode validator has the country option that can be changed dynamically a select element.

The dynamic option can be determined by:

  • A string
  • Name of field which defines the value
  • Name of function which returns the value
  • A function returns the value

In the third and fourth cases, the callback function must follow the format:

function(value, validator, $field) {
    // value is the value of field
    // validator is the FormValidation instance
    // $field is the jQuery element representing field element
}

Supported validators

Below is the list of validators supporting dynamic option. Refer to specific validator document to see the full list of options.

Validator Dynamic option
between validator min, max
choice validator min, max
date validator min, max
greaterThan validator value
iban validator country
id validator country
lessThan validator value
phone validator country
stringLength validator min, max
vat validator country
zipCode validator country
If you develop your own validator which support dynamic option, the getDynamicOption() method might be useful. You should look at the source of validators above to see how this method is used.

To illustrate how powerful this concept is, take a look at the following example.

Assume that your form uses zipCode validator to validate a zipcode. The next sections show you how to use four ways above to define option value.

You can use the following sample zipcodes for testing:

Country Valid Zipcode Invalid Zipcode
United States 12345 123
Italy IT-12345 123

Using string as usual

It's easy for you if the country code option is set initially and can't be changed:

$(document).ready(function() {
    $('#zipcodeForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'US',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipCodeForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">US zipcode</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#zipCodeForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'US',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
</script>

What happen if you want the country to be changeable, for example, by a select element. With the dynamic option concept, it can be done easily by setting the country option as:

Using name of element defining the option value

<!-- The element for choosing a country -->
<select class="form-control" name="countrySelectBox">
    <option value="US">United States</option>
    <option value="CA">Canada</option>
    <option value="DK">Denmark</option>
    <option value="IT">Italy</option>
    <option value="NL">Netherlands</option>
    <option value="SE">Sweden</option>
    <option value="GB">United Kingdom</option>
</select>
$(document).ready(function() {
    $('#zipcodeElementForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'countrySelectBox',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipCodeForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Country:</label>
        <div class="col-xs-5">
            <select class="form-control" name="countrySelectBox">
                <option value="US">United States</option>
                <option value="CA">Canada</option>
                <option value="DK">Denmark</option>
                <option value="IT">Italy</option>
                <option value="NL">Netherlands</option>
                <option value="SE">Sweden</option>
                <option value="GB">United Kingdom</option>
            </select>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Zipcode</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#zipCodeForm')
        .formValidation({
            framework: 'bootstrap',
            icon: {
                valid: 'glyphicon glyphicon-ok',
                invalid: 'glyphicon glyphicon-remove',
                validating: 'glyphicon glyphicon-refresh'
            },
            fields: {
                code: {
                    validators: {
                        zipCode: {
                            country: 'countrySelectBox',
                            message: 'The value is not valid zipcode'
                        }
                    }
                }
            }
        })
        .on('change', '[name="countrySelectBox"]', function() {
            // Revalidate the zipcode after changing the country
            $('#zipCodeForm').formValidation('revalidateField', 'code');
        });
});
</script>

Using name of function returning the option value

<!-- The element for choosing a country -->
<select class="form-control" name="countrySelectBox">
    <option value="US">United States</option>
    <option value="CA">Canada</option>
    <option value="DK">Denmark</option>
    <option value="IT">Italy</option>
    <option value="NL">Netherlands</option>
    <option value="SE">Sweden</option>
    <option value="GB">United Kingdom</option>
</select>
function getCountryCode(value, validator, $field) {
    // Return the selected country code
    return $('[name="countrySelectBox"]').val();

    // You can use getFieldElements() method
    // return validator.getFieldElements('countrySelectBox').val();
};

$(document).ready(function() {
    $('#zipcodeFunctionNameForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'getCountryCode',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipCodeForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Country:</label>
        <div class="col-xs-5">
            <select class="form-control" name="countrySelectBox">
                <option value="US">United States</option>
                <option value="CA">Canada</option>
                <option value="DK">Denmark</option>
                <option value="IT">Italy</option>
                <option value="NL">Netherlands</option>
                <option value="SE">Sweden</option>
                <option value="GB">United Kingdom</option>
            </select>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Zipcode</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>

<script>
function getCountryCode(value, validator, $field) {
    // Return the selected country code
    return validator.getFieldElements('countrySelectBox').val();
};

$(document).ready(function() {
   $('#zipCodeForm')
        .formValidation({
           framework: 'bootstrap',
            icon: {
                valid: 'glyphicon glyphicon-ok',
                invalid: 'glyphicon glyphicon-remove',
                validating: 'glyphicon glyphicon-refresh'
            },
            fields: {
                code: {
                    validators: {
                        zipCode: {
                            country: 'getCountryCode',
                            message: 'The value is not valid zipcode'
                        }
                    }
                }
            }
        })
        .on('change', '[name="countrySelectBox"]', function() {
            $('#zipCodeForm').formValidation('revalidateField', 'code');
        });
});
</script>

Using function returning the option value

$(document).ready(function() {
    $('#zipcodeElementForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: function(value, validator, $field) {
                            return $('[name="countrySelectBox"]').val();

                            // You can use getFieldElements() method
                            // return validator.getFieldElements('countrySelectBox').val();
                        },
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipCodeForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Country:</label>
        <div class="col-xs-5">
            <select class="form-control" name="countrySelectBox">
                <option value="US">United States</option>
                <option value="CA">Canada</option>
                <option value="DK">Denmark</option>
                <option value="IT">Italy</option>
                <option value="NL">Netherlands</option>
                <option value="SE">Sweden</option>
                <option value="GB">United Kingdom</option>
            </select>
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Zipcode</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#zipCodeForm')
        .formValidation({
            framework: 'bootstrap',
            icon: {
                valid: 'glyphicon glyphicon-ok',
                invalid: 'glyphicon glyphicon-remove',
                validating: 'glyphicon glyphicon-refresh'
            },
            fields: {
                code: {
                    validators: {
                        zipCode: {
                            country: function(value, validator, $field) {
                                return validator.getFieldElements('countrySelectBox').val();
                            },
                            message: 'The value is not valid zipcode'
                        }
                    }
                }
            }
        })
        .on('change', '[name="countrySelectBox"]', function() {
            $('#getCountryCode').formValidation('revalidateField', 'code');
        });
});
</script>

Dynamic message

Looking back to the zipcode example above, you will realize that the message is static:

<!-- The element for choosing a country -->
<select class="form-control" name="countrySelectBox">
    <option value="US">United States</option>
    <option value="CA">Canada</option>
    <option value="DK">Denmark</option>
    <option value="IT">Italy</option>
    <option value="NL">Netherlands</option>
    <option value="SE">Sweden</option>
    <option value="GB">United Kingdom</option>
</select>
$(document).ready(function() {
    $('#dynamicMessageForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'countrySelectBox',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});

As you see, the message is always The value is not valid zipcode and does not change nomatter what the country is.

Fortunately, it is easy to convert this message to a dynamic one. Just use %s characters in the message and they will be replaced with the country you choose:

$(document).ready(function() {
    $('#dynamicMessageForm').formValidation({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'countrySelectBox',
                        // %s will be replaced with "US zipcode", "Italian postal code", and so on
                        // when you choose the country as US, IT, etc.
                        message: 'The value is not valid %s zipcode'
                    }
                }
            }
        }
    });
});
<form id="dynamicMessageForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Country:</label>
        <div class="col-xs-5">
            <select class="form-control" name="countrySelectBox">
                <option value="US">United States</option>
                <option value="CA">Canada</option>
                <option value="DK">Denmark</option>
                <option value="IT">Italy</option>
                <option value="NL">Netherlands</option>
                <option value="SE">Sweden</option>
                <option value="GB">United Kingdom</option>
            </select>
        </div>
    </div>
    
    <div class="form-group">
        <label class="col-xs-3 control-label">Zipcode</label>
        <div class="col-xs-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#dynamicMessageForm')
        .formValidation({
            framework: 'bootstrap',
            icon: {
                valid: 'glyphicon glyphicon-ok',
                invalid: 'glyphicon glyphicon-remove',
                validating: 'glyphicon glyphicon-refresh'
            },
            fields: {
                code: {
                    validators: {
                        zipCode: {
                            country: 'countrySelectBox',
                            message: 'The value is not valid %s zipcode'
                        }
                    }
                }
            }
        })
        .on('change', '[name="countrySelectBox"]', function() {
            // Revalidate the zipcode after changing the country
            $('#dynamicMessageForm').formValidation('revalidateField', 'code');
        });
});
</script>

Below is the list of validators supporting dynamic message:

Validator Example
between validator 
between: {
    min: ...,
    max: ...,
    message: 'Please enter a value between %s and %s'
}
choice validator 
choice: {
    min: ...,
    max: ...,
    message: 'Please choose %s - %s options'
}
greaterThan validator 
greaterThan: {
    value: ...,
    message: 'Please enter a value greater than or equal to %s'
}
iban validator 
iban: {
    country: ...,
    message: 'Please enter a valid IBAN number in %s'
}
id validator 
id: {
    country: ...,
    message: 'Please enter a valid %s identification number'
}
lessThan validator 
lessThan: {
    value: ...,
    message: 'Please enter a value less than or equal to %s'
}
phone validator 
phone: {
    country: ...,
    message: 'Please enter a valid phone number in %s'
}
stringLength validator 
stringLength: {
    min: ...,
    max: ...,
    message: 'Please enter value between %s and %s characters long'
}
vat validator 
vat: {
    country: ...,
    message: 'Please enter a valid %s VAT number'
}
zipCode validator 
zipCode: {
    country: ...,
    message: 'Please enter a valid %s'
}
callback validator 
callback: {
    callback: function(value, validator, $field) {
        // ... Do your logic checking
        if (...) {
            return {
                valid: true,    // or false
                message: 'The error message'
            }
        }

        return {
            valid: false,       // or true
            message: 'Other error message'
        }
    }
}
promise validator 
promise: {
    promise: function(value, validator, $field) {
        var dfd = new $.Deferred();

        // ... Do your logic checking

        // Resolve when particular task is done
        dfd.resolve({
            valid: true, // or false
            message: 'The error message'
        });

        // You can reject if there's error
        dfd.reject({
            message: 'Other message'
        });

        return dfd.promise();
    }
}
remote validator

The backend returns a JSON string that consists of valid and message keys:

{ valid: true, message: 'The error message' }
Your own validator 
(function($) {
    FormValidation.Validator.yourValidatorName = {
        validate: function(validator, $field, options) {
            // ... Do your logic checking
            if (...) {
                return {
                    valid: true,    // or false
                    message: 'The error message'
                }
            }

            return {
                valid: false,       // or true
                message: 'Other error message'
            }
        }
    };
}(window.jQuery));

Turning off dynamic message

To turn off dynamic message:

Validator Example
between validator 
between: {
    min: 20,
    max: 100,
    message: 'Please enter a value between 20 and 100'
}
callback validator 
callback: {
    callback: function(value, validator, $field) {
        // ... Do your logic checking
        return true;        // or false
    }
}
promise validator 
promise: {
    promise: function(value, validator, $field) {
        var dfd = new $.Deferred();

        // ... Do your logic checking

        // Resolve when particular task is done
        dfd.resolve({
            valid: true,  // or false
        });

        // You can reject if there's error
        dfd.reject();

        return dfd.promise();
    }
}
remote validator

The backend returns a JSON string that consists of valid key:

{ valid: true }
Your own validator 
(function($) {
    FormValidation.Validator.yourValidatorName = {
        validate: function(validator, $field, options) {
            // ... Do your logic checking
            return true;        // or false
        }
    };
}(window.jQuery));

Events

Similar to the settings, there are also events for form, field and validator. Each event can be set by one of three ways:

  • Listening to event using jQuery on(eventName, callback)
  • Using option
  • Using HTML 5 attributes

Form events

Event Description
init.form.fv Triggered after the form is initialized by the plugin
prevalidate.form.fv Triggered before validating the form
err.form.fv Triggered when the form is invalid
success.form.fv Triggered when the form is valid
added.field.fv Triggered after adding dynamic field
removed.field.fv Triggered after removing given field
Usage Example
Listening to event 
$(document).ready(function() {
    $(form)
        // on('init.form.fv') must be declared
        // before calling .formValidation(options)
        .on('init.form.fv', function(e, data) {
            // $(e.target)  --> The form instance
            // data.fv      --> The FormValidation instance
            // data.options --> The form options

            // Do something ...
        })

        .formValidation(options)

        .on('prevalidate.form.fv', function(e) {
            // $(e.target) --> The form instance
            // $(e.target).data('formValidation')
            //             --> The FormValidation instance

            // Do something ...
        })

        .on('err.form.fv', function(e) {
            // The e parameter is same as one
            // in the prevalidate.form.fv event above

            // Do something ...
        })

        .on('success.form.fv', function(e) {
            // The e parameter is same as one
            // in the prevalidate.form.fv event above

            // Do something ...
        })

        .on('added.field.fv', function(e, data) {
            // $(e.target)  --> The form instance
            // $(e.target).data('formValidation')
            //              --> The FormValidation instance

            // data.field   --> The field name
            // data.element --> The new field element
            // data.options --> The new field options

            // Do something ...
        })

        .on('removed.field.fv', function(e, data) {
            // The e and data parameters are same as one
            // in the added.field.fv event above

            // Do something ...
        });
});
Using option 
$(document).ready(function() {
    $(form)
        .formValidation({
            onPreValidate: function(e) {
                // Do something ...
            },
            onError: function(e) {
                // Do something ...
            },
            onSuccess: function(e) {
                // Do something ...
            }
        });
});
Using HTML 5 attributes 
<form data-fv-onprevalidate="onPreValidateForm"
      data-fv-onerror="onFormError"
      data-fv-onsuccess="onFormSuccess"></form>
function onPreValidateForm(e) {
    // Do something ...
};

function onFormError(e) {
    // Do something ...
};

function onFormSuccess(e) {
    // Do something ...
};

$(document).ready(function() {
    $(form).formValidation(options);
});
Examples

Field events

Event Description
init.field.fv Triggered after the field is initialized by the plugin
err.field.fv Triggered when any field is invalid
success.field.fv Triggered when any field is valid
status.field.fv

Triggered when field changes status. Each field has four possible status:

  • NOT_VALIDATED: The field is not validated yet
  • VALIDATING: The field is being validated
  • INVALID: The field is invalid
  • VALID: The field is valid
Usage Example
Listening to event 
$(document).ready(function() {
    $(form)
        // on('init.field.fv') must be declared
        // before calling .formValidation(options)
        .on('init.field.fv', function(e, data) {
            // $(e.target)  --> The field element
            // data.fv      --> The FormValidation instance
            // data.field   --> The field name
            // data.element --> The field element
        })

        .formValidation(options)

        .on('err.field.fv', function(e, data) {
            // The e and data parameters are the same
            // as one in the init.field.fv event above

            // Do something ...
        })

        .on('success.field.fv', function(e, data) {
            // The e and data parameters are the same
            // as one in the init.field.fv event above

            // Do something ...
        })

        .on('status.field.fv', function(e, data) {
            // The e and data parameters are the same
            // as one in the init.field.fv event above

            // data.status --> New field status
            // data.validator --> The name of current validator

            // Do something ...
        });
});

If you want to trigger this event for particular field, for example, the name="email" field:

Usage Example
Listening to event 
$(document).ready(function() {
    $(form)
        // on('init.field.fv') must be declared
        // before calling .formValidation(options)
        .on('init.field.fv', '[name="email"]', function(e, data) {
            // Do something ...
        })

        .formValidation(options)

        .on('err.field.fv', '[name="email"]', function(e, data) {
            // Do something ...
        })

        .on('success.field.fv', '[name="email"]', function(e, data) {
            // Do something ...
        })

        .on('status.field.fv', '[name="email"]', function(e, data) {
            // Do something ...
        });
});
Using option 
$(document).ready(function() {
    $(form)
        .formValidation({
            fields: {
                email: {
                    onError: function(e, data) {
                        // Do something ...
                    },
                    onSuccess: function(e, data) {
                        // Do something ...
                    },
                    onStatus: function(e, data) {
                        // Do something ...
                    },
                    validators: {
                        ...
                    }
                }
            }
        });
});
Using HTML 5 attributes 
<form>
    ...
    <input type="text" name="email" class="form-control"
        data-fv-emailaddress="true"
        data-fv-onerror="onFieldError"
        data-fv-onsuccess="onFieldSuccess"
        data-fv-onstatus="onFieldStatus" />
    ...
</form>
function onFieldError(e, data) {
    // Do something ...
};

function onFieldSuccess(e, data) {
    // Do something ...
};

function onFieldStatus(e, data) {
    // Do something ...
};

$(document).ready(function() {
    $(form).formValidation(options);
});
Examples

Validator events

Event Description
err.validator.fv Triggered when field doesn't pass given validator
success.validator.fv Triggered when field passes given validator
Usage Example
Listening to event 
$(document).ready(function() {
    $(form)
        .formValidation(options)

        .on('err.validator.fv', function(e, data) {
            // $(e.target)    --> The form instance
            // data.field     --> The field name
            // data.element   --> The field element
            // data.validator --> The validator name

            // Do something ...
        })

        .on('success.validator.fv', function(e, data) {
            // The e parameter is the same as one
            // in the err.validator.fv event above

            // Do something ...
        });
});
Using option 
$(document).ready(function() {
    $(form)
        .formValidation({
            fields: {
                email: {
                    validators: {
                        emailAddress: {
                            onError: function(e, data) {
                                // Do something ...
                            },
                            onSuccess: function(e, data) {
                                // Do something ...
                            },
                            // ... other validator options ...
                        }
                    }
                }
            }
        });
});
Using HTML 5 attributes 
<form>
    ...
    <input type="text" name="email" class="form-control"
        data-fv-emailaddress="true"
        data-fv-emailaddress-onerror="onEmailAddressError"
        data-fv-emailaddress-onsuccess="onEmailAddressSuccess" />
    ...
</form>
function onEmailAddressError(e, data) {
    // Do something ...
};

function onEmailAddressSuccess(e, data) {
    // Do something ...
};

$(document).ready(function() {
    $(form).formValidation(options);
});
Examples
← Getting started API →