Settings

Edit on Github

The BootstrapValidator plugin can be called with the full options as sample code below:

$(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"]',
    submitHandler: null,
    trigger: null,
    fields: ...
});

You can use HTML attributes for form to set the options:

Option Equivalent HTML attribute Default
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
}
live data-bv-live 'enabled'
message data-bv-message 'This value is not valid'
submitButtons data-bv-submitbuttons '[type="submit"]'
submitHandler n/a null
threshold data-bv-threshold null
trigger data-bv-trigger null
fields n/a null

So the Javascript code above is equivalent to the following usage:

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

<script>
$(document).ready(function() {
    $(formSelector).bootstrapValidator({
        submitHandler: null,
        fields: ...
    });
});
</script>

It's also possible to set validator options for each field using HTML attributes. Look at each validator documentation for more details.

excluded

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

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:

feedbackIcons

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.

There are two popular questions with the feedback icon usage:

The feedback icons aren't shown when using custom Bootstrap theme from 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>

The feedback icons aren't shown properly for some elements such as select box or when using with other element such as Bootstrap Datetime Picker, Bootstrap Color Picker, etc.

Bootstrap defines feedback icon position as following:

.form-horizontal .has-feedback .form-control-feedback {
    top: 0;
    right: 15px;
}

You can override this to adjust feedback icon position:

.form-horizontal .has-feedback .form-control-feedback {
    top: 0;
    right: -15px;
}
.form-horizontal .has-feedback .input-group .form-control-feedback {
    top: 0;
    right: -30px;
}
<!-- Include CSS required by Bootstrap Datetime Picker -->
<link href="/bootstrap-validator/vendor/bootstrap-datetimepicker/css/bootstrap-datetimepicker.min.css" rel="stylesheet" />

<!-- Override feedback icon position -->
<style type="text/css">
#feedbackIconForm .has-feedback .form-control-feedback {
    top: 0;
    right: -15px;
}
#feedbackIconForm .has-feedback .input-group .form-control-feedback {
    top: 0;
    right: -30px;
}
</style>
<form id="feedbackIconForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-lg-3 control-label">Full name</label>
        <div class="col-lg-5">
            <input type="text" class="form-control" name="fullName" />
        </div>
    </div>
    <div class="form-group">
        <label class="col-lg-3 control-label">Gender</label>
        <div class="col-lg-5">
            <select class="form-control" name="gender">
                <option value="">Choose gender</option>
                <option value="male">Male</option>
                <option value="female">Female</option>
                <option value="other">Other</option>
            </select>
        </div>
    </div>
    <div class="form-group">
        <label class="col-lg-3 control-label">Date of birth</label>
        <div class="col-lg-5">
            <div class="input-group date" id="dobPicker" data-date-format="YYYY/DD/MM">
                <input type="text" class="form-control" name="dob" />
                <span class="input-group-addon">
                    <span class="glyphicon-calendar glyphicon"></span>
                </span>
            </div>
        </div>
    </div>
</form>
<!-- Include JS required by Bootstrap Datetime Picker -->
<script src="/bootstrap-validator/vendor/momentjs/moment.min.js"></script>
<script src="/bootstrap-validator/vendor/bootstrap-datetimepicker/js/bootstrap-datetimepicker.min.js"></script>
<script>
$(document).ready(function() {
    $('#dobPicker')
        .datetimepicker({
            pickTime: false
        })
        .on('dp.change dp.show', function(e) {
            $('#feedbackIconForm')
                .data('bootstrapValidator')
                .updateStatus('dob', 'NOT_VALIDATED', null)
                .validateField('dob');
        });
    $('#feedbackIconForm').bootstrapValidator({
        message: 'This value is not valid',
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            fullName: {
                validators: {
                    notEmpty: {
                        message: 'The full name is required and cannot be empty'
                    }
                }
            },
            gender: {
                validators: {
                    notEmpty: {
                        message: 'The gender is required and cannot be empty'
                    }
                }
            },
            dob: {
                validators: {
                    notEmpty: {
                        message: 'The date of birth is required and cannot be empty'
                    },
                    date: {
                        format: 'YYYY/DD/MM',
                        message: 'The value is not a valid date'
                    }
                }
            }
        }
    });
});
</script>

live

Live validating mode. Can be one of 3 values:

Value Description
enabled 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

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

submitButtons

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

submitHandler

Custom submit handler:

submitHandler: function(validator, form, submitButton) {
}
Parameter Type Description
validator BootstrapValidator The instance of BootstrapValidator
form jQuery Representing the current form
submitButton jQuery Representing the submit button which is clicked

This option is useful when you want to use Ajax to submit the form data:

submitHandler: function(validator, form, submitButton) {
    // Use Ajax to submit form data
    $.post(form.attr('action'), form.serialize(), function(result) {
        // ... process the result ...
    }, 'json');
}

By default, submitHandler is null.

If you want to submit the form inside your custom submit handler, use the defaultSubmit() method:

submitHandler: function(validator, form, submitButton) {
    // Do your task
    // ...
    // Submit the form
    validator.defaultSubmit();
}

threshold

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

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

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

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

    <div class="form-group">
        <div class="col-lg-9 col-lg-offset-3">
            <button type="submit" class="btn btn-primary">Validate</button>
        </div>
    </div>
</form>
<script>
$(document).ready(function() {
    $('#thresholdForm').bootstrapValidator({
        message: 'This value is not valid',
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        // Set default threshold for all fields. It is null by default
        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 in, such as radio, checkbox, select, etc.
                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

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 fields section.

fields

The fields which need to be validated.

fields: {
    ...
    <fieldName>: {
        enabled: true,
        message: 'This value is not valid',
        container: null,
        selector: null,
        trigger: null,

        // Map the validator name with its options
        validators: {
            ...
            <validatorName>: <validatorOptions>
            ...
        }
    }
    ...
}

Replace the <fieldName> with the field name, which is the value of name attribute. If the field cannot be defined by the name attribute, you can use the selector option described below.

The validator options for each field include:

Option Equivalent HTML attribute Type Description
enabled n/a Boolean Enable or disable the field validators
message data-bv-message String The default error message for the field
container data-bv-container String The CSS selector to indicate the element showing the error messages. Take a look at container example below.
selector data-bv-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. Take a look at selector example below.
threshold data-bv-threshold String Do not live validate field until the length of field value exceed this number
trigger data-bv-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. See the trigger example.
validators n/a Object Map the validator name <validatorName> with validator options <validatorOptions>

The <validatorName> can be the name of the built-in validator which are described in the Validators page.

container 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="containerForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-lg-3 control-label">Full name</label>
        <div class="col-lg-4">
            <input type="text" class="form-control" name="firstName" placeholder="First name" />
            <span class="help-block" id="firstNameMessage"></span>
        </div>
        <div class="col-lg-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-lg-3 control-label">Username</label>
        <div class="col-lg-5">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>
</form>
<script>
$(document).ready(function() {
    $('#containerForm').bootstrapValidator({
        fields: {
            firstName: {
                container: '#firstNameMessage',
                validators: {
                    ...
                }
            },
            lastName: {
                container: '.lastNameMessage',
                validators: {
                    ...
                }
            },
            username: {
                validators: {
                    ...
                }
            }
        }
    });
});
</script>

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

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

    <div class="form-group">
        <label class="col-lg-3 control-label">CVV</label>
        <div class="col-lg-2">
            <input type="text" class="form-control cvvNumber" />
        </div>
    </div>
</form>
<script>
$(document).ready(function() {
    $('#paymentForm').bootstrapValidator({
        fields: {
            ccNumber: {
                selector: '#ccNumber',
                validators: {
                    ...
                }
            },
            expMonth: {
                selector: '[data-stripe="exp-month"]',
                validators: {
                    ...
                }
            },
            expYear: {
                selector: '[data-stripe="exp-year"]',
                validators: {
                    ...
                }
            },
            cvvNumber: {
                selector: '.cvvNumber',
                validators: {
                    ...
                }
            }
        }
    });
});
</script>

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

trigger 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-lg-3 control-label">Title</label>
        <div class="col-lg-5">
            <input type="text" class="form-control" name="title" />
        </div>
    </div>

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

    <div class="form-group">
        <label class="col-lg-3 control-label">Description</label>
        <div class="col-lg-9">
            <textarea rows="10" class="form-control" name="description"></textarea>
        </div>
    </div>
</form>
<script>
$(document).ready(function() {
    $('#triggerForm').bootstrapValidator({
        message: 'This value is not valid',
        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'
                    }
                }
            }
        }
    });
});
</script>

Comments

If you want to report a bug, please submit the issue on Github. Do NOT post the issue here.

For a general question or feedback, use the form below.