Getting Started

Edit on Github

Download

Choose the package you want to download:

Release

Including the plugin, its validator source and minified versions.
It should be used in the production site.

Download v0.4.5

Source code

Including the source code, examples and building script. Download if you want to play with or develop new validators.

Download Source

Older versions

For older versions, take a look at the Releases page.

See what's news in v0.4.5, released on 2014-05-15

Installing with Bower

It's also possible to get the latest release from bower:

$ bower install bootstrapValidator

BootstrapValidator also can be found on the official jQuery plugins page.

What's Included?

bootstrapvalidator/
├── dist
│   ├── css
│   │   ├── bootstrapValidator.css
│   │   └── bootstrapValidator.min.css
│   └── js
│       ├── bootstrapValidator.js
│       └── bootstrapValidator.min.js
└── src
    ├── css
    │   ├── bootstrapValidator.css
    │   └── bootstrapValidator.min.css
    └── js
        ├── validator
        │   ├── base64.js
        │   ├── between.js
        │   ├── callback.js
        │   └── ...
        └── bootstrapValidator.js

The src directory consists of the original source files. src/js/bootstrapValidator.js is not compressed and doesn't include any validators.

The dist directory consists of files which is combined and compressed. dist/js/bootstrapValidator(.min).js includes all validators. It should be used in the production site.

Usage

It takes only 3 steps to use the plugin:

Including Library

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/dist/css/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>

Next, requires the plugin javascript file:

// Either use the compressed version (recommended in the production site)
<script type="text/javascript" src="/path/to/dist/js/bootstrapValidator.min.js"></script>

// Or use the original one with all validators included
<script type="text/javascript" src="/path/to/dist/js/bootstrapValidator.js"></script>

// Or use the plugin with required validators
<script type="text/javascript" src="/path/to/src/js/bootstrapValidator.js"></script>
<script type="text/javascript" src="/path/to/src/js/validator/...validator..."></script>

Writing Form

Since BootstrapValidator is designed to use with Bootstrap, your form must be structured using Bootstrap classes.

If your form is NOT structured by Bootstrap classes (the element containing field and associated label does NOT have form-group class), you will see the following error in the Console:
Uncaught RangeError: Maximum call stack size exceeded

Do not use the properties of a form, such as submit, reset, length, method to set the name or id attribute of form, field elements. Name conflicts can cause the problem.

For example, you cannot submit the form after validating if use submit to name the Submit button:

<button type="submit" name="submit" class="btn btn-primary">Submit</button>

DOMLint has a complete list of rules to check the markup for these kind of problems.

The plugin supports all possible kind of Bootstrap form, including:

Basic Form

<form>
    <div class="form-group">
        <label>Username</label>
        <input type="text" class="form-control" name="username" />
    </div>
    <div class="form-group">
        <label>Email address</label>
        <input type="text" class="form-control" name="email" />
    </div>
</form>

Basic Form without Labels

<form>
    <div class="form-group">
        <input type="text" class="form-control" name="username" placeholder="Username" />
    </div>
    <div class="form-group">
        <input type="text" class="form-control" name="email" placeholder="Email address" />
    </div>
</form>

Inline Form

<form class="form-inline">
    <div class="form-group">
        <input type="text" class="form-control" name="username" placeholder="Username" />
    </div>
    <div class="form-group">
        <input type="text" class="form-control" name="email" placeholder="Email address" />
    </div>
</form>

Horizontal Form

<form class="form-horizontal">
    <div class="form-group">
        <label class="col-lg-3 control-label">Username</label>
        <div class="col-lg-9">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>
    <div class="form-group">
        <label class="col-lg-3 control-label">Email address</label>
        <div class="col-lg-9">
            <input type="text" class="form-control" name="email" />
        </div>
    </div>
</form>

It also supports multiple fields on the same row:

<form class="form-horizontal">
    <div class="form-group">
        <label class="col-lg-2 control-label">Account</label>
        <div class="col-lg-4">
            <input type="text" class="form-control" name="username" placeholder="Username" />
        </div>
        <div class="col-lg-4">
            <input type="text" class="form-control" name="email" placeholder="Email address" />
        </div>
    </div>
</form>

Calling Plugin

Call the plugin to validate the form as following:

$(document).ready(function() {
    $(formSelector).bootstrapValidator({
        excluded: ...,
        feedbackIcons: ...,
        live: 'enabled',
        message: 'This value is not valid',
        submitButtons: 'button[type="submit"]',
        submitHandler: null,
        trigger: null,
        fields: ...
    });
});

For example, to validate the sample registration form above, the plugin might be called as:

$(document).ready(function() {
    $('.registerForm').bootstrapValidator({
        message: 'This value is not valid',
        feedbackIcons: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        fields: {
            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'
                    },
                    regexp: {
                        regexp: /^[a-zA-Z0-9_]+$/,
                        message: 'The username can only consist of alphabetical, number and underscore'
                    }
                }
            },
            email: {
                validators: {
                    notEmpty: {
                        message: 'The email is required and cannot be empty'
                    },
                    emailAddress: {
                        message: 'The input is not a valid email address'
                    }
                }
            }
        }
    });
});

Look at the Settings page to see the meaning of plugin options.

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.