Bootstrap Form Validation with jQuery
bsValidate is a lightweight jQuery Plugin that provides basic validation of Twitter Bootstrap (v3) forms. Current validation capabilities include:
- Required fields
- Email formatting
- Character limit
- Compare two fields
- Regular Expression
- Custom function
I plan to build on this list and offer more validation options in the future, so stay tuned!
Prerequisites
JS
- jQuery
CSS
- Bootstrap (not a requirement if you plan to include your own styles that use the same classes)
Installation
With Bower
bower install bsvalidate
With Git
git clone https://github.com/matthewjmink/bsValidate.git
Use
After your reference to jQuery, add a reference to the jquery.bsvalidate.min.js
file within your project:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script> <script src="/path/to/js/jquery.bsvalidate.min.js"></script>
Basic Use
The basic use of the plugin is intended to enforce required fields only. Required fields are indicated with the .required
class, or the [required]
attribute.
HTML
<form id="theForm"> <!-- Fields need to be wrapped in a .field-group to ensure proper display of error messages --> <div class="form-group"> <!-- A label should be included, either with the <label> tag or an element given the .label class --> <label class="control-label">Name</label> <!-- This field will be required, because it uses the .required class --> <input type="text" name="name" class="form-control required" /> </div> <div class="form-group"> <label class="control-label">Email</label> <!-- This field will also be required, because it uses the [required] attribute --> <input type="text" name="email" class="form-control" required /> </div> <div class="form-group"> <label class="control-label">Message</label> <!-- No validation will be applied to this field --> <textarea name="message" class="form-control" rows="8"></textarea> </div> <div class="form-group"> <input type="submit" class="btn btn-primary" value="Submit" /> </div> </form>
JavaScript
$('#theForm').bsValidate();
Advanced Use
Alternatively, a fields
object can be specified in place of (or in addition to) element attributes to list the fields that should be validated, along with the validation requirements. The [name]
attribute is used as the key name for each field, unless the formGroupSelector
property is specified.
HTML
<form id="theForm"> <div class="form-group"> <label class="control-label">Name</label> <input type="text" name="name" class="form-control" /> </div> <div class="form-group"> <label class="control-label">Email</label> <input type="text" name="email" class="form-control" /> </div> <div class="form-group"> <label class="control-label">Message</label> <textarea name="message" class="form-control" rows="8"></textarea> </div> <div class="form-group"> <input type="submit" class="btn btn-primary" value="Submit" /> </div> </form>
JavaScript
/* * This has the same effect as the basic example, * except custom messages have been included. */ $('#theForm').bsValidate({ fields: { name: { required: { helpText: "Please enter your name.", alert: "Oops! You forgot to tell us your name. Please enter it below." } }, email: { required: { helpText: "Please enter your email.", alert: "We hate to pry, but could we get your email address please? We'll need one to write back." } } } });
Available Options
{ // A list of fields, using the [name] attributes as key names (see example above). Each indicated field // should include the necessary validation options (see below). // DEFAULT: {} (OBJECT) fields: {}, // The DOM element into which the alerts should be prepended when validation errors occur. // DEFAULT: this (JQUERY OBJECT) alertTarget: $(element), // A jQuery selector used to determine which fields should be required. // DEFAULT: "input.required,textarea.required,select.required,[required]" (STRING) requiredSelector: "", // Determines which attribute should be used to identify the form elements from the {fields} object. // DEFAULT: "name" (STRING) attrAsKey: "", // A jQuery selector used to identify the parent element for each field. // DEFAULT: ".form-group" (STRING) formGroupSelector: "", // For <select> fields, change what the plugin considers as "blank" (i.e. "-- Select --") // DEFAULT: "" (STRING) blankSelectValue: "", // Combine alerts into a single alert box, rather than separate boxes for each message, as an unordered // list. Optionally, the unordered list can be replaced with a single message if {alertMessage} is set // to something other than null (see below). // DEFAULT: false (BOOLEAN) mergeAlerts: false, // Use a single, general alert message rather than individual messages for each validation error. // If {mergeAlerts} is set to TRUE, this message will replace the list of validation messages. // DEFAULT: null (STRING) alertMessage: null, // Help text only shows on field change by default. Set this to TRUE to display help text for // fields on form submission as well. // DEFAULT: false (BOOLEAN) toggleHelpTextOnSubmit: false, // If a field has a dependency, changing the value of the parent field will trigger validation on the child. // Set this property to FALSE if you do not want this behavior. // DEFAULT: true (BOOLEAN) triggerDependentValidationOnChange: true, // Automatically scroll the page on form submission so the alerts are in view. // DEFAULT: true (BOOLEAN) autoScrollToAlerts: true, // Set {novalidate} to false to use browser validation for fields with the [required] attribute (browser // validation is overriden by default). // DEFAULT: false (BOOLEAN) novalidate: true, // Callback function that fires after form submission, but before any validation takes place. // Could be used to clear out existing error message from server-side validation prior to displaying bsValidate messages. // DEFAULT: function(){} (FUNCTION) before: function(){}, // Callback function that fires after all fields pass validation, but before the form submits. // In case you want to submit your form with JavaScript (Ajax) or run more JavaScript before submitting, // an event parameter is passed to the function, and event.preventDefault() can be used. // DEFAULT: function(e){} (FUNCTION) success: function(e){}, // Callback function that fires if one or more fields fail validation. By default, the form is prevented // from submitting. // DEFAULT: function(e){ e.preventDefault(); } (FUNCTION) fail: function(e){} }
Validation options
{ // Require the field required: { helpText: "Custom required help text.", alert: "Custom alert for required field.", // If this field depends on others, you can set validation conditions. // NOTE: The fields referenced in this property need to be registered // in the {fields} object, even if no validation is desired for the // referenced field. Setting the field to an empty object {} will // register it without enforcing validation. dependency: { // Use the [name] attribute of the field(s) we're checking against. isBlank: 'fieldName', // Dependencies can be a comma-separated list of field names isNotBlank: 'fieldName2,fieldName3' } }, // Make sure it looks like an email address email: { helpText: "Custom email address help text.", alert: "Custom alert for an email address field." }, // Limit the number of characters characters: { limit: 140, helpText: "Custom character limit help text.", alert: "Custom alert for a field with a character limit (probably a <textarea> field)." }, // Compare the field value against a regular expression pattern regex: { pattern: /^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$/g, helpText: "This example checks for a URL.", alert: "But you can put any valid regex pattern here" }, // Compare the field value against the value of another field match: { field: "fieldName", helpText: "Use the [name] attribute of the field we're checking against.", alert: "This compares the literal string values of the two fields. So '0.1' and '.10' do not match and will not validate." } // Use a custom validation function to evaluate a field value. custom: { fn: function(inputElem){ return inputElem.val() !== 'desired value'; }, helpText: "The input element (jQuery object) is passed into the function." alert: "This can be used for more complex scenarios than the standard options can accommodate. The function needs to return a Boolean value. An expression that evaluates to TRUE will trigger the validation.", } }