your failure messageNote: You can include this in the callback response in stead, to customise against the user's error

The callback function will be passed the element (wrapped in
jQuery), the field value, and a response function to call when
ready.

The response function expects a single variable, a hash
containing 'value', 'valid' and optionally 'message'.

The value must be returned, as this is checked against the
current value and stale responses are ignored. The 'valid' item
in the hash should evaluate to true only if the given value is
valid. The message item in the hash, if given, will override
the current message on the validator.

Sound a bit complex? Don't worry and take a look at the code
tab, its pretty self explanatory.

Warning: While waiting
for your function to use the callback, the validator assumes
the field is valid. This is to guard against something failing
server-side and stopping the user from submitting the form. If
your callback takes a long time, the user could be able to
submit the form with invalid data without realising.

your failure messageNote: You can include this in the ajax response in stead, to customise against the user's error

The ajax call will be passed the field name and the field value.

The response is expected as a JSON hash
containing 'value', 'valid' and optionally 'message'.

Value must be returned, as this is checked against the
current value so stale responses are ignored. The 'valid' item
in the hash should evaluate to true only if the given value is
valid. The message item in the hash, if given, will override
the current message on the validator.

Sound a bit complex? Don't worry and take a look at the server
tab, its pretty self explanatory.

Warning: While waiting
for AJAX call, the validator assumes the field is valid. This
is to guard against a something failing and stopping the user
from submitting the form. If your ajax takes a long time, the
user could be able to submit the form with invalid data without
realising.

Have you noticed how all the validation messages data-attributes look the same?

data-validation-validatorname-message

Validators are attached with names, so you can have multiple of
the same validator if you just name them differently.

In the form above, I've added two Regex validators, one requiring uppercase, the other requiring at least one number.
Because they are named differently ('uppercase' and 'containsnumber' respectively) they are both applied rather than cancelling eachother out.

You can also use the HTML5 validators multiple times by specifying them in data-attribute format, such as data-validator-myvalidator-maxlength=10 to use the maxlength HTML5 validator, for example.

Configuration

sniffHtml

Internally, jqBootstrapValidation only uses data attributes.
By default, it will also sniff for native HTML5 form validation attributes, as detailed above.

If you decide this isn't what you want, you can restrict jqBootstrapValidation to only data attributes by setting sniffHtml to false when calling it on your form elements.
$(...).jqBootstrapValidation({sniffHtml: false});

preventSubmit

By default, jqBootstrapValidtion will prevent forms from submitting if any of their elements fail validation by jqBootstrapValidation.

If you decide this isn't what you want, you can allow submitting of potentially invalid data for validation server-side (or in case you think someone might have a genuine case for exceptional data).
$(...).jqBootstrapValidation({preventSubmit: false});

submitError

A javascript callback, used when a user is attempting to submit a form with invalid input.

Parameter

Description

$form

The form element which has the user attempted to submit (wrapped in jQuery)

event

The submit event (note this may have already been cancelled before you receive it depending on your preventSubmit option).

errors

An object consisting of the names of fields as keys, and the array of errors as values.

If you decide you want to react to the invalid submit attempt, you can write a function directly into the jqBootstrapValidation call:

Note: The event parameter is a full jQuery event and may be manipulated as normal.

autoAdd

If your form is missing help blocks, for example if you don't want an empty element hanging around near 'terms and conditions' check boxes where no explanation would normally be needed, jqBootstrapValidation will add them for you automatically.

If you decide this isn't what you want, for example if you only want the error styling without a warning message, you can stop jqBootstrapValidation from creating extra elements.
$(...).jqBootstrapValidation({autoAdd: {helpBlocks: false}});

filter

jqBootstrapValidation doesn't assume anything about your form, so if you need to ignore some validators in multi-stage forms you can optionally filter them out of the submit event with the filter option.

The this variable is set to a single element. If you return false, it will be ignored on submit events. For example, the below ignores all elements that are not visible on the page:

hasErrors

Override

WARNING This has the potential to break jqBootstrapValidation. Tread carefully.

Internally, all of jqBootstrapValidation's functions are stored in one big object, which you can override by calling the "override" function with a new object to merge on top of it. Anything you don't set, is left as it was.

Note that as the objects are merged together, you can define your own extra functions, options, etc.

This allows you to duck punch your own solutions, and set up the options in one place rather than on every call to .jqBootstrapValidation()

options

Question If you override the defaults, will you need to tell anyone else?

You can override the default options by calling the 'override' function and setting the 'options' key with the values you'd use when calling .jqBootstrapValidation() on a set of elements. As this updates the internal object, all subsequent calls to .jqBootstrapValidation() will use the new options.

For example, to stop jqBootstrapValidation from preventing an invalid form from being submitted by default:

FAQ

Where is the date/time/tel/currency validator?

Simply put, I'm in the UK and you probably aren't. English might not even be your first language.

I can't possibly know how you write dates, when even the UK and USA can't agree.

I can't find a nice cross platform way of detecting someone's region preferences easily. If there is enough demand (@ReactiveRaven) I'll add region support, but for now you may be better finding a non-restrictive regex for your local format.

Where do I ask a question?

The best place to reach me is on twitter @ReactiveRaven. If you don't have a twitter account, you could email me in stead. It turns out I'm terrible at answering emails though, so please don't be surprised if I'm slow to respond. Sorry!

If you think you've found a bug, please do file an issue on github or better yet, fork and send a pull request.

Where do I report a bug?

If you've found a bug, please do file an issue on github or better yet, fork and send a pull request.