---
layout: default
title: Validator
slug: validator
lead: "A simple and user-friendly form validator plugin for Bootstrap 3"
---


  <!-- Dropdowns
  ================================================== -->
  <div class="bs-docs-section">
    <div class="page-header">
      <h1 id="validator">Validator <small>validator.js</small></h1>
    </div>

    <h2 id="validator-examples">Examples</h2>
    <p>Add validation to your forms with this simple plugin.</p>

    <div class="bs-example">
      <form data-toggle="validator" role="form">
        <div class="form-group">
          <label for="inputName" class="control-label">Name</label>
          <input type="text" class="form-control" id="inputName" placeholder="Cina Saffary" required>
        </div>
        <div class="form-group">
          <label for="inputTwitter" class="control-label">Twitter</label>
          <div class="input-group">
            <span class="input-group-addon">@</span>
            <input type="text" pattern="^([_A-z0-9]){3,}$" maxlength="20" class="form-control" id="inputTwitter" placeholder="1000hz" required>
          </div>
          <span class="help-block with-errors">Up to 20 letters, numbers and underscores</span>
        </div>
        <div class="form-group">
          <label for="inputEmail" class="control-label">Email</label>
          <input type="email" class="form-control" id="inputEmail" placeholder="Email" data-error="Bruh, that email address is invalid" required>
          <div class="help-block with-errors"></div>
        </div>
        <div class="form-group">
          <label for="inputPassword" class="control-label">Password</label>
          <div class="form-inline row">
            <div class="form-group col-sm-6">
              <input type="password" data-toggle="validator" data-minlength="6" class="form-control" id="inputPassword" placeholder="Password" required>
              <span class="help-block">Minimum of 6 characters</span>
            </div>
            <div class="form-group col-sm-6">
              <input type="password" class="form-control" id="inputPasswordConfirm" data-match="#inputPassword" data-match-error="Whoops, these don't match" placeholder="Confirm" required>
              <div class="help-block with-errors"></div>
            </div>
          </div>
        </div>
        <div class="form-group">
          <div class="radio">
            <label>
              <input type="radio" name="underwear" required>
              Boxers
            </label>
          </div>
          <div class="radio">
            <label>
              <input type="radio" name="underwear" required>
              Briefs
            </label>
          </div>
        </div>
        <div class="form-group">
          <div class="checkbox">
            <label>
              <input type="checkbox" id="terms" data-error="Before you wreck yourself" required>
              Check yourself
            </label>
            <div class="help-block with-errors"></div>
          </div>
        </div>
        <div class="form-group">
          <button type="submit" class="btn btn-primary">Submit</button>
        </div>
      </form>
    </div> <!-- /example -->
{% highlight html %}
<form data-toggle="validator" role="form">
  <div class="form-group">
    <label for="inputName" class="control-label">Name</label>
    <input type="text" class="form-control" id="inputName" placeholder="Cina Saffary" required>
  </div>
  <div class="form-group">
    <label for="inputTwitter" class="control-label">Twitter</label>
    <div class="input-group">
      <span class="input-group-addon">@</span>
      <input type="text" pattern="^([_A-z0-9]){3,}$" maxlength="20" class="form-control" id="inputTwitter" placeholder="1000hz" required>
    </div>
    <span class="help-block with-errors">Up to 20 letters, numbers and underscores</span>
  </div>
  <div class="form-group">
    <label for="inputEmail" class="control-label">Email</label>
    <input type="email" class="form-control" id="inputEmail" placeholder="Email" data-error="Bruh, that email address is invalid" required>
    <div class="help-block with-errors"></div>
  </div>
  <div class="form-group">
    <label for="inputPassword" class="control-label">Password</label>
    <div class="form-group col-sm-6">
      <input type="password" data-minlength="6" class="form-control" id="inputPassword" placeholder="Password" required>
      <span class="help-block">Minimum of 6 characters</span>
    </div>
    <div class="form-group col-sm-6">
      <input type="password" class="form-control" id="inputPasswordConfirm" data-match="#inputPassword" data-match-error="Whoops, these don't match" placeholder="Confirm" required>
      <div class="help-block with-errors"></div>
    </div>
    </div>
  </div>
  <div class="form-group">
    <div class="radio">
      <label>
        <input type="radio" name="underwear" required>
        Boxers
      </label>
    </div>
    <div class="radio">
      <label>
        <input type="radio" name="underwear" required>
        Briefs
      </label>
    </div>
  </div>
  <div class="form-group">
    <div class="checkbox">
      <label>
        <input type="checkbox" id="terms" data-error="Before you wreck yourself" required>
        Check yourself
      </label>
      <div class="help-block with-errors"></div>
    </div>
  </div>
  <div class="form-group">
    <button type="submit" class="btn btn-primary">Submit</button>
  </div>
</form>
{% endhighlight %}


    <h2 id="validator-usage">Usage</h2>
    Form validation can be enabled in markup via the data-api or via JavaScript.

    Automatically enable form validation by adding <code>data-toggle="validator"</code> to your form element.

{% highlight html %}
<form role="form" data-toggle="validator">
  ...
</form>
{% endhighlight %}

    Or activate validation via JavaScript:

{% highlight js %}
$('#myForm').validator()
{% endhighlight %}

    <h3 id="validator-markup">Markup</h3>
    <p>Follow Bootstrap's <a href="http://getbootstrap.com/css/#forms" target="_blank">examples</a> for appropriate form markup.</p>

    <p>Validation rules are specified on form inputs via the following standard HTML5 attributes:</p>
    <ul>
      <li><code>type="email"</code></li>
      <li><code>type="url"</code></li>
      <li><code>type="number"</code>, with additional constraints via <code>max</code> and <code>min</code> attributes</li>
      <li><code>pattern="Reg(ular )?Exp(ression)?"</code> (for input types of <code>text</code>, <code>search</code>, <code>tel</code>, <code>url</code> or <code>email</code>)</li>
      <li><code>required</code></li>
    </ul>

    <p>As well as the following non-standard attributes:</p>
    <ul>
      <li><code>data-match="#inputToMatch"</code> to ensure two fields match, e.g. password confirmations</li>
      <li><code>data-minlength="5"</code> to enforce a minimum amount of characters</li>
      <li><code>data-remote="/path/to/remote/validator"</code> to make an AJAX request to determine if the field is valid or not. Be sure to give the input a <code>name</code> attribute, as the request will be sent to <code>/path/to/remote/validator?&lt;name&gt;=&lt;value&gt;</code>. The remote endpoint should return a <code>200 OK</code> if the field is valid, and a <code>4xx</code> otherwise.</li>
    </ul>

    <p>To display error messages, include a container after the input field with both <code>help-block</code> and <code>with-errors</code> classes.</p>


{% highlight html %}
<form role="form" data-toggle="validator">
  <div class="form-group">
    <label for="inputEmail">Email</label>
    <input type="email" id="inputEmail">
    <div class="help-block with-errors"></div>
  </div>
</form>
{% endhighlight %}


    <h3 id="validator-options">Options</h3>
    <p>Options can be passed via data attributes or JavaScript. For data attributes, append the option name to <code>data-</code>, as in <code>data-delay=""</code>.</p>
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead>
         <tr>
           <th style="width: 100px;">Name</th>
           <th style="width: 100px;">type</th>
           <th style="width: 50px;">default</th>
           <th>description</th>
         </tr>
        </thead>
        <tbody>
         <tr>
           <td>delay</td>
           <td>number</td>
           <td>500</td>
           <td>Number of milliseconds to wait before displaying an error on a form field.</td>
         </tr>
         <tr>
           <td>html</td>
           <td>boolean</td>
           <td>false</td>
           <td>Insert HTML into the error messages. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</td>
         </tr>
         <tr>
           <td>disable</td>
           <td>boolean</td>
           <td>true</td>
           <td>Disable the submit button until the form is valid and all required fields are complete.</td>
         <tr>
           <td>errors</td>
           <td>object</td>
           <td>sensible defaults</td>
           <td><p>Error messages to show for each type of validation. Defaults to:</p>
{% highlight js %}
errors: {
  match: "Does not match",
  minlength: "Not long enough"
}
{% endhighlight %}
           </td>
         </tr>
        </tbody>
      </table>
    </div><!-- /.table-responsive -->
    <div class="bs-callout bs-callout-info">
      <h4>Error messages for individual form fields</h4>
      <p>Error messages for individual form fields can alternatively be specified through the use of data attributes. You can specify an error message for each type of validator on a field, i.e. <code>data-match-error=""</code> or use <code>data-error=""</code> for a blanket error message to show for any errors on that field.</p>
    </div>

    <h3 id="validator-methods"> Methods</h3>
    <h4>$().validator(options)</h4>
    <p>Attaches a validator to a form collection.</p>

    <h4>$().validator('validate')</h4>
    <p>Immediately validates the entire form.</p>

    <h4>$().validator('destroy')</h4>
    <p>Destroys form validator and cleans up data left behind.</p>

    <h3 id="validator-events">Events</h3>
    <p>All events are fired on the form element and provide a reference to the form field to which the event pertains via <code>event.relatedTarget</code>.</p>

    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead>
          <tr>
            <th style="width: 150px;">Event Type</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>validate.bs.validator</td>
            <td>This event fires immediately when a form field is validated.</td>
          </tr>
          <tr>
            <td>invalid.bs.validator</td>
            <td>This event is fired when a form field becomes invalid. Field errors are provided via <code>event.detail</code>.</td>
          </tr>
          <tr>
            <td>valid.bs.validator</td>
            <td>This event is fired when a form field becomes valid. Previous field errors are provided via <code>event.detail</code>.</td>
          </tr>
          <tr>
            <td>validated.bs.validator</td>
            <td>This event is fired after a form field has been validated.</td>
          </tr>
        </tbody>
      </table>
    </div><!-- ./bs-table-responsive -->

  </div>