BootstrapValidator
A jQuery plugin to validate form fields. Use with Bootstrap 3
Features
- Built from scratch
- Many built-in validators
- It is easy to write new validator
Required
Demo
You can see the live demo here:
Usage
Since the bootstrapValidator plugin requires jQuery and Bootstrap 3, you have to include the required CSS and JS files to your page:
<link rel="stylesheet" href="/path/to/bootstrap/css/bootstrap.css"/>
<link rel="stylesheet" href="/path/to/bootstrapValidator.min.css"/>
<script type="text/javascript" src="/path/to/jquery/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="/path/to/bootstrap/js/bootstrap.min.js"></script>
<script type="text/javascript" src="/path/to/bootstrapValidator.min.js"></script>
Call the plugin to validate the form as following:
$(document).ready(function() {
$(<form Selector>).bootstrapValidator({
// The default error message for all fields
// You can specify the error message for any fields
message: ...,
// The submit buttons selector
// These buttons will be disabled when the form input are invalid
submitButtons: ...,
// Custom submit handler
// The handler has two arguments
// - validator is the instance of BootstrapValidator
// - form is jQuery object representing the current form
// By default, submitHandler is null
submitHandler: function(validator, form) {
},
// Live validating. Can be one of 3 values:
// - 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
live: 'enabled',
// The fields which need to be validated
fields: {
...
// The field name
// It is value of the name attribute
<fieldName>: {
// The default error message for this field
message: ...,
// Array of validators
validators: {
...
<validatorName>: <validatorOptions>
...
}
}
...
}
});
});
The <validatorName>
can be the name of the built-in validator which are described in the Validators section
Validators
Below is the list of built-in validators sorted in alphabetical order:
Validator name | Description |
---|---|
between | Check if the input value is between (strictly or not) two given numbers |
callback | Return the validity from a callback method |
creditCard | Validate a credit card number |
different | Return true if the input value is different with given field's value |
digits | Return true if the value contains only digits |
emailAddress | Validate an email address |
greaterThan | Return true if the value is greater than or equals to given number |
hexColor | Validate a hex color |
identical | Check if the value is the same as one of particular field |
lessThan | Return true if the value is less than or equals to given number |
notEmpty | Check if the value is empty |
regexp | Check if the value matches given Javascript regular expression |
remote | Perform remote checking via Ajax request |
stringLength | Validate the length of a string |
uri | Validate an URL address |
usZipCode | Validate a US zip code |
The validator options are described in the following section:
(The options masked with * are required)
Between Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
min (*) | n/a | The lower value in the range |
max (*) | n/a | The upper value in the range |
inclusive | true | Can be true or false. If true, the input value must be in the range strictly |
Callback Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
callback (*) | n/a | The callback method |
The callback method must follow the format below:
function(fieldValue, validator) {
// fieldValue is the value of field
// validator is instance of BootstrapValidator
// Check the field validity
// return true or false
}
Different Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
field (*) | n/a | The name of field that will be used to compare with current one |
GreaterThan Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
value (*) | n/a | The number to make a comparison to |
inclusive | false | Can be true or false |
If true, the input value must be greater than the comparison one | ||
If false, the input value must be greater than or equal to the comparison one |
Identical Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
field (*) | n/a | The name of field that will be used to compare with current one |
LessThan Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
value (*) | n/a | The number to make a comparison to |
inclusive | false | Can be true or false |
If true, the input value must be less than the comparison one | ||
If false, the input value must be less than or equal to the comparison one |
Regexp Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
regexp (*) | n/a | The Javascript regular expression |
Remote Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
url (*) | n/a | The remote URL that responses an encoded JSON of array containing the valid key |
StringLength Validator
Option name | Default | Description |
---|---|---|
message | n/a | The error message |
min | n/a | The minimum length |
max | n/a | The maximum length. One of min , max options is required |
Install
You can use bower to install BootstrapValidator:
$ bower install bootstrapValidator
Write new validator
A validator has to follow the syntax:
(function($) {
$.fn.bootstrapValidator.validators.<validatorName> = {
/**
* @param {BootstrapValidator} validator The validator plugin instance
* @param {jQuery} $field The jQuery object represents the field element
* @param {Object} options The validator options
* @returns {boolean}
*/
validate: function(validator, $field, options) {
// You can get the field value
// var value = $field.val();
//
// Perform validating
// ...
//
// return true if the field value is valid
// otherwise return false
}
};
}(window.jQuery));
<validatorName>
is the validator name.
Since the validators are distinct by the names, <validatorName>
has to be different with built-in validators.
To apply the validator to particular field:
$(form).bootstrapValidator({
fields: {
<fieldName>: {
// Replace <validatorName> with the name of validator
// <validatorOptions> will be passed as third parameter of the
// validate(validator, $field, options) method
<validatorName>: <validatorOptions>
}
}
});
To see how built-in validators are developed, you can look at their sources located at the src/js/validator
directory.
Build
BootstrapValidator uses grunt to simplify building process.
From the BootstrapValidator root directory, execute the following commands to install the dependent packages (the administrator permission might be required):
$ npm install grunt --save-dev
$ npm install grunt-contrib-concat --save-dev
$ npm install grunt-contrib-copy --save-dev
$ npm install grunt-contrib-cssmin --save-dev
$ npm install grunt-contrib-uglify --save-dev
$ npm install grunt-contrib-watch --save-dev
Then, uses grunt to build:
$ grunt
If you want grunt to generate scripts whenever the original scripts (located in src
) change, use the following command:
$ grunt watch
The generated scripts (including source and compressed versions) are placed inside the dist
directory.
Release History
Look at the Change Log
Author
Nguyen Huu Phuoc ([Email](mailto: phuoc@huuphuoc.me) / Twitter / Github)
Big thanks to the contributors:
- Vu Minh Khang ([Email](mailto: khangvm530@gmail.com) / Github)
License
Copyright (c) 2013 Nguyen Huu Phuoc
BootstrapValidator is licensed under the MIT license.