v0.5.3 is released on 2014.11.05!

Settings

Improve it on Github

Settings structure

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

The BootstrapValidator plugin can be called as following:

$(formSelector).bootstrapValidator({
    ... Form settings go here ...
    fields: {
        specificFieldName: {
            ... Field settings go here ...

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

                    ... specific validator settings ...
                }
            }
        }
    }
});

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

For example, the following call:

$(formSelector).bootstrapValidator({
    excluded: [':disabled', ':hidden', ':not(:visible)'],
    feedbackIcons: {
        valid: 'glyphicon glyphicon-ok',
        invalid: 'glyphicon glyphicon-remove',
        validating: 'glyphicon glyphicon-refresh'
    },
    live: 'enabled',
    message: 'This value is not valid',
    submitButtons: 'button[type="submit"]',
    trigger: null,
    fields: ...
});

is equivalent with the one below:

<form data-bv-message="This value is not valid"
      data-bv-feedbackicons-valid="glyphicon glyphicon-ok"
      data-bv-feedbackicons-invalid="glyphicon glyphicon-remove"
      data-bv-feedbackicons-validating="glyphicon glyphicon-refresh"
      data-bv-submitbuttons='button[type="submit"]'
      data-bv-live="enabled">
    ...
</form>
$(document).ready(function() {
    $(formSelector).bootstrapValidator({
        fields: ...
    });
});

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

Examples

Form settings

Below is the list of settings for form:

Option Equivalent HTML attribute Default
autoFocus data-bv-autofocus true
container data-bv-container n/a
excluded data-bv-excluded [':disabled', ':hidden', ':not(:visible)']
feedbackIcons data-bv-feedbackicons-valid, data-bv-feedbackicons-invalid, data-bv-feedbackicons-validating 
{
    valid: null,
    invalid: null,
    validating: null
}
group data-bv-group '.form-group'
live data-bv-live 'enabled'
message data-bv-message 'This value is not valid'
submitButtons data-bv-submitbuttons '[type="submit"]'
threshold data-bv-threshold null
trigger data-bv-trigger null
verbose data-bv-verbose true
fields n/a null

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.

container: String

Indicate where the error messages are shown.

Value Description
CSS selector All error messages are placed in element defined by this CSS selector
tooltip Error messages of each field are placed inside a Bootstrap tooltip.
popover Error messages of each field are placed inside a Bootstrap popover.

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-sm-3 control-label">Full name</label>
        <div class="col-sm-4">
            <input type="text" class="form-control" name="firstName" placeholder="First name" />
        </div>
        <div class="col-sm-4">
            <input type="text" class="form-control" name="lastName" placeholder="Last name" />
        </div>
    </div>

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

    <div class="form-group">
        <div class="col-sm-9 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#containerForm').bootstrapValidator({
        container: 'tooltip',
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

excluded: Boolean

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 BootstrapValidator 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.

feedbackIcons: Object

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

This feature requires Bootstrap v3.1.0 or later. Since Bootstrap doesn't provide any methods to know its version, this option cannot be on/off automatically. In other word, to use this feature you have to upgrade your Bootstrap to v3.1.0 or later.

It supports Glyphicons (included in Bootstrap):

feedbackIcons: {
    valid: 'glyphicon glyphicon-ok',
    invalid: 'glyphicon glyphicon-remove',
    validating: 'glyphicon glyphicon-refresh'
}

and FontAwesome icons (don't forget to insert FontAwesome CSS in your head):

feedbackIcons: {
    valid: 'fa fa-check',
    invalid: 'fa fa-times',
    validating: 'fa fa-refresh'
}

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

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

group: String

CSS selector indicates the parent element of field. By default, it is .form-group.

Following Bootstrap form structure, each field and its label are wrapped inside .form-group element.

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 group 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.

We would like to know 5 recent projects you have done:

Project Role URL 
<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">
    <table class="table table-condensed">
        <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>

    <button type="submit" class="btn btn-default">Validate</button>
</form>
$(document).ready(function() {
    $('#groupForm').bootstrapValidator({
        container: 'tooltip',
        group: 'td',
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

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

message: String

The default error message for all fields. You can specify the error message for any fields.

submitButtons: String

The submit buttons selector. These buttons will be disabled when the form input are invalid.

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: 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: 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-bv-autofocus
container data-bv-container
enabled data-bv-enabled
excluded data-bv-excluded
feedbackIcons data-bv-feedbackicons
group data-bv-group
message data-bv-message
selector data-bv-selector
threshold data-bv-threshold
trigger data-bv-trigger
verbose data-bv-verbose

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.

container: String

Indicate where the error messages are shown.

Value Description
CSS selector Error messages are placed in element defined by this CSS selector
tooltip Error messages are placed inside a Bootstrap tooltip.
popover Error messages are placed inside a Bootstrap popover.

Example

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

<form id="fieldContainerForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Full name</label>
        <div class="col-sm-4">
            <input type="text" class="form-control" name="firstName" placeholder="First name" />
            <span class="help-block" id="firstNameMessage"></span>
        </div>
        <div class="col-sm-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-sm-3 control-label">Username</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#fieldContainerForm').bootstrapValidator({
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            firstName: {
                container: '#firstNameMessage',
                validators: {
                    notEmpty: {
                        message: 'The first name is required and cannot be empty'
                    }
                }
            },
            lastName: {
                container: '.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'
                    }
                }
            }
        }
    });
});

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.

excluded: Boolean

Indicate whether or not the field is excluded.

feedbackIcons: Boolean

Enable or disable feedback icons.

Example

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

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

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

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

    <div class="form-group">
        <div class="col-sm-5 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#fieldIconsForm').bootstrapValidator({
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            address: {
                feedbackIcons: 'false',
                validators: {
                    notEmpty: {
                        message: 'The address is required and cannot be empty'
                    }
                }
            },
            city: {
                feedbackIcons: false,
                validators: {
                    notEmpty: {
                        message: 'The city is required and cannot be empty'
                    }
                }
            },
            phone: {
                feedbackIcons: true,
                validators: {
                    notEmpty: {
                        message: 'The phone number is required and cannot be empty'
                    },
                    phone: {
                        country: 'US',
                        message: 'The phone number is not valid'
                    }
                }
            }
        }
    });
});

group: String

CSS selector indicates the parent element of field. By default, it is .form-group.

message: String

The default error message for the field.

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.

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-sm-3 control-label">Credit card number</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" id="ccNumber" />
        </div>
    </div>

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

    <div class="form-group">
        <label class="col-sm-3 control-label">CVV</label>
        <div class="col-sm-2">
            <input type="text" class="form-control cvvNumber" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#paymentForm').bootstrapValidator({
        feedbackIcons: {
            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"]',
                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"]',
                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'
                    }
                }
            }
        }
    });
});

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

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-sm-3 control-label">Full name</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="fullname" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-sm-3 control-label">Gender</label>
        <div class="col-sm-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-sm-3 control-label">Phone number</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="phone" />
        </div>
    </div>

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

    <div class="form-group">
        <div class="col-sm-9 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#thresholdForm').bootstrapValidator({
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

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="triggerForm" method="post" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Title</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="title" />
        </div>
    </div>

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

    <div class="form-group">
        <label class="col-sm-3 control-label">Description</label>
        <div class="col-sm-9">
            <textarea rows="10" class="form-control" name="description"></textarea>
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#triggerForm').bootstrapValidator({
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

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-bv-{validatorname}
message data-bv-{validatorname}-message

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-bv-notempty />

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

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

// Disable validator
$(form)
    .bootstrapValidator('enableFieldValidators', fullName, false, 'notEmpty');

Example

<form id="validatorEnabledForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Full name</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="fullName" />
        </div>
    </div>

    <div class="form-group">
        <div class="col-sm-5 col-sm-offset-3">
            <button type="submit" class="btn btn-default">Validate</button>
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#validatorEnabledForm').bootstrapValidator({
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

message: String

The error message of validator for field.

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 BootstrapValidator 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
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').bootstrapValidator({
        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-sm-3 control-label">US zipcode</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#zipcodeForm').bootstrapValidator({
        feedbackIcons: {
            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'
                    }
                }
            }
        }
    });
});

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').bootstrapValidator({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'countrySelectBox',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipcodeElementForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Country:</label>
        <div class="col-sm-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-sm-3 control-label">Zipcode</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#zipcodeElementForm')
        .bootstrapValidator({
            feedbackIcons: {
                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
            $('#zipcodeElementForm').bootstrapValidator('revalidateField', 'code');
        });
});

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').bootstrapValidator({
        fields: {
            code: {
                validators: {
                    zipCode: {
                        country: 'getCountryCode',
                        message: 'The value is not valid zipcode'
                    }
                }
            }
        }
    });
});
<form id="zipcodeFunctionNameForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Country:</label>
        <div class="col-sm-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-sm-3 control-label">Zipcode</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>
function getCountryCode(value, validator, $field) {
    // Return the selected country code
    return validator.getFieldElements('countrySelectBox').val();
};

$(document).ready(function() {
   $('#zipcodeFunctionNameForm')
        .bootstrapValidator({
            feedbackIcons: {
                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() {
            $('#zipcodeFunctionNameForm').bootstrapValidator('revalidateField', 'code');
        });
});

Using function returning the option value

$(document).ready(function() {
    $('#zipcodeElementForm').bootstrapValidator({
        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="zipcodeCallbackForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Country:</label>
        <div class="col-sm-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-sm-3 control-label">Zipcode</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#zipcodeCallbackForm')
        .bootstrapValidator({
            feedbackIcons: {
                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').bootstrapValidator('revalidateField', 'code');
        });
});

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').bootstrapValidator({
        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').bootstrapValidator({
        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'
                    }
                }
            }
        }
    });
});
<form id="dynamicMessageForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">Country:</label>
        <div class="col-sm-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-sm-3 control-label">Zipcode</label>
        <div class="col-sm-5">
            <input type="text" class="form-control" name="code" />
        </div>
    </div>
</form>
$(document).ready(function() {
    $('#dynamicMessageForm')
        .bootstrapValidator({
            feedbackIcons: {
                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'
                        }
                    }
                }
            }
        })
        .on('change', '[name="countrySelectBox"]', function() {
            // Revalidate the zipcode after changing the country
            $('#dynamicMessageForm').bootstrapValidator('revalidateField', 'code');
        });
});

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'
        }
    }
}
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($) {
    $.fn.bootstrapValidator.validators.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
    }
}
remote validator

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

{ valid: true }
Your own validator 
(function($) {
    $.fn.bootstrapValidator.validators.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.bv Triggered after the form is initialized by the plugin
error.form.bv Triggered when the form is invalid
success.form.bv Triggered when the form is valid
added.field.bv Triggered after adding dynamic field
removed.field.bv Triggered after removing given field
Usage Example
Listening to event 
$(document).ready(function() {
    $(form)
        // on('init.form.bv') must be declared
        // before calling .bootstrapValidator(options)
        .on('init.form.bv', function(e, data) {
            // $(e.target)  --> The form instance
            // data.bv      --> The BootstrapValidator instance
            // data.options --> The form options

            // Do something ...
        })

        .bootstrapValidator(options)

        .on('error.form.bv', function(e) {
            // $(e.target) --> The form instance
            // $(e.target).data('bootstrapValidator')
            //             --> The BootstrapValidator instance

            // Do something ...
        })

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

            // Do something ...
        })

        .on('added.field.bv', function(e, data) {
            // $(e.target)  --> The form instance
            // $(e.target).data('bootstrapValidator')
            //              --> The BootstrapValidator instance

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

            // Do something ...
        })

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

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

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

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

Examples

Field events

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

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.bv') must be declared
        // before calling .bootstrapValidator(options)
        .on('init.field.bv', function(e, data) {
            // $(e.target)  --> The field element
            // data.bv      --> The BootstrapValidator instance
            // data.field   --> The field name
            // data.element --> The field element
        })

        .bootstrapValidator(options)

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

            // Do something ...
        })

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

            // Do something ...
        })

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

            // data.status --> New field status

            // 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.bv') must be declared
        // before calling .bootstrapValidator(options)
        .on('init.field.bv', '[name="email"]', function(e, data) {
            // Do something ...
        })

        .bootstrapValidator(options)

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

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

        .on('status.field.bv', '[name="email"]', function(e, data) {
            // Do something ...
        });
});
Using option 
$(document).ready(function() {
    $(form)
        .bootstrapValidator({
            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-bv-emailaddress
        data-bv-onerror="onFieldError"
        data-bv-onsuccess="onFieldSuccess"
        data-bv-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).bootstrapValidator(options);
});

Examples

Validator events

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

        .on('error.validator.bv', 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.bv', function(e, data) {
            // The e parameter is the same as one
            // in the error.validator.bv event above

            // Do something ...
        });
});
Using option 
$(document).ready(function() {
    $(form)
        .bootstrapValidator({
            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-bv-emailaddress
        data-bv-emailaddress-onerror="onEmailAddressError"
        data-bv-emailaddress-onsuccess="onEmailAddressSuccess" />
    ...
</form>
function onEmailAddressError(e, data) {
    // Do something ...
};

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

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

Example