Validation

Best practices

Poorly communicated errors can be frustrating for users. Apply the following guidelines when handling errors:

  • Write error messages in clear and simple language. User should be able to understand the problem while reading an error message.
  • Include suggestions on how to resolve the error.
  • Avoid technical jargon.
  • Don’t use negative words and never blame the user.
  • Use a general error message to communicate that something went wrong but also ensure specific messages are used inline and placed where the error took place.

Try to prevent errors from occurring in the first place. For example; if a date in the future is required, disable the ability to select a date in the past. If errors do occur let the user know right away. Make sure it’s clear what the error is, and where it occurred. If possible, implement inline validation with real-time feedback right after the answered question. This will increase success rates and satisfaction, and decrease errors made and completion time.

Symbolic colours (such as red for error) and icons are often used to help signify meaning to a user for error messages, warnings and success messages. Never rely solely on colours or icons, they should be used along with supporting text so that the information is accessible for all users.

Please provide a valid email address.

Do: Use specific messages where the error took place

Please provide a valid email address.

Don't: Rely solely on colours and/or icons to communicate errors

How it works

Provide valuable, actionable feedback to your users with HTML5 form validation–available in all our supported browsers. Choose from the browser default validation feedback, or implement custom messages with our built-in classes and starter JavaScript.

We currently recommend using custom validation styles, as native browser default validation messages are not consistently exposed to assistive technologies in all browsers (most notably, Chrome on desktop and mobile).

Here’s how form validation works with Bootstrap:

  • HTML form validation is applied via CSS’s two pseudo-classes, :invalid and :valid. It applies to <input>, <select>, and <textarea> elements.
  • Bootstrap scopes the :invalid and :valid styles to parent .was-validated class, usually applied to the <form>. Otherwise, any required field without a value shows up as invalid on page load. This way, you may choose when to activate them (typically after form submission is attempted).
  • To reset the appearance of the form (for instance, in the case of dynamic form submissions using AJAX), remove the .was-validated class from the <form> again after submission.
  • As a fallback, .is-invalid and .is-valid classes may be used instead of the pseudo-classes for server side validation. They do not require a .was-validated parent class.
  • Due to constraints in how CSS works, we cannot (at present) apply styles to a <label> that comes before a form control in the DOM without the help of custom JavaScript.
  • All modern browsers support the constraint validation API, a series of JavaScript methods for validating form controls.
  • Feedback messages may utilize the browser defaults (different for each browser, and unstylable via CSS) or our custom feedback styles with additional HTML and CSS.
  • You may provide custom validity messages with setCustomValidity in JavaScript.

With that in mind, consider the following demos for our custom form validation styles, optional server side classes, and browser defaults.

Custom styles

For custom Bootstrap form validation messages, you’ll need to add the novalidate boolean attribute to your <form>. This disables the browser default feedback tooltips, but still provides access to the form validation APIs in JavaScript. Try to submit the form below; our JavaScript will intercept the submit button and relay feedback to you. When attempting to submit, you’ll see the :invalid and :valid styles applied to your form controls.

Custom feedback styles apply custom colours, borders, focus styles, and background icons to better communicate feedback. Background icons for <select>s are only available with .custom-select, and not .form-control.

Looks good!
Looks good!
Please provide a valid city.
Please provide a valid province.
Please provide a valid postal code. 
<form class="needs-validation" novalidate>
  <div class="form-row">
    <div class="col-sm-6 mb-3">
      <label for="validationCustom01">First name</label>
      <input type="text" class="form-control" id="validationCustom01" value="Mark" required>
      <div class="valid-feedback">
        Looks good!
      </div>
    </div>
    <div class="col-sm-6 mb-3">
      <label for="validationCustom02">Last name</label>
      <input type="text" class="form-control" id="validationCustom02" value="Otto" required>
      <div class="valid-feedback">
        Looks good!
      </div>
    </div>
  </div>
  <div class="form-row">
    <div class="col-sm-5 mb-3">
      <label for="validationCustom03">City</label>
      <input type="text" class="form-control" id="validationCustom03" required>
      <div class="invalid-feedback">
        Please provide a valid city.
      </div>
    </div>
    <div class="col-sm-4 mb-3">
      <label for="validationCustom04">Province</label>
      <input type="text" class="form-control" id="validationCustom04" required>
      <div class="invalid-feedback">
        Please provide a valid province.
      </div>
    </div>
    <div class="col-sm-3 col-6 mb-3">
      <label for="validationCustom05">Postal code</label>
      <input type="text" class="form-control" id="validationCustom05" required>
      <div class="invalid-feedback">
        Please provide a valid postal code.
      </div>
    </div>
  </div>
  <div class="form-group">
    <div class="custom-control custom-checkbox">
      <input type="checkbox" class="custom-control-input" id="invalidCheck" required>
      <label class="custom-control-label" for="invalidCheck">
        Agree to terms and conditions
      </label>
    </div>
  </div>
  <button class="btn btn-primary" type="submit">Submit form</button>
</form>

<script>
// Example starter JavaScript for disabling form submissions if there are invalid fields
(function() {
  'use strict';
  window.addEventListener('load', function() {
    // Fetch all the forms we want to apply custom Bootstrap validation styles to
    var forms = document.getElementsByClassName('needs-validation');
    // Loop over them and prevent submission
    var validation = Array.prototype.filter.call(forms, function(form) {
      form.addEventListener('submit', function(event) {
        if (form.checkValidity() === false) {
          event.preventDefault();
          event.stopPropagation();
        }
        form.classList.add('was-validated');
      }, false);
    });
  }, false);
})();
</script>

Browser defaults

Not interested in custom validation feedback messages or writing JavaScript to change form behaviours? All good, you can use the browser defaults. Try submitting the form below. Depending on your browser and OS, you’ll see a slightly different style of feedback.

While these feedback styles cannot be styled with CSS, you can still customize the feedback text through JavaScript.

<form>
  <div class="form-row">
    <div class="col-sm-6 mb-3">
      <label for="validationDefault01">First name</label>
      <input type="text" class="form-control" id="validationDefault01" value="Mark" required>
    </div>
    <div class="col-sm-6 mb-3">
      <label for="validationDefault02">Last name</label>
      <input type="text" class="form-control" id="validationDefault02" value="Otto" required>
    </div>
  </div>
  <div class="form-row">
    <div class="col-sm-5 mb-3">
      <label for="validationDefault03">City</label>
      <input type="text" class="form-control" id="validationDefault03" required>
    </div>
    <div class="col-sm-4 mb-3">
      <label for="validationDefault04">Province</label>
      <input type="text" class="form-control" id="validationDefault04" required>
    </div>
    <div class="col-sm-3 col-6 mb-3">
      <label for="validationDefault05">Postal code</label>
      <input type="text" class="form-control" id="validationDefault05" required>
    </div>
  </div>
  <div class="form-group">
    <div class="custom-control custom-checkbox">
      <input type="checkbox" class="custom-control-input" id="invalidCheck2" required>
      <label class="custom-control-label" for="invalidCheck2">
        Agree to terms and conditions
      </label>
    </div>
  </div>
  <button class="btn btn-primary" type="submit">Submit form</button>
</form>

Server side

We recommend using client-side validation, but in case you require server-side validation, you can indicate invalid and valid form fields with .is-invalid and .is-valid. Note that .invalid-feedback is also supported with these classes.

Looks good!
Looks good!
Please provide a valid city.
Please provide a valid province.
Please provide a valid postal code.
You must agree before submitting. 
<form>
  <div class="form-row">
    <div class="col-sm-6 mb-3">
      <label for="validationServer01">First name</label>
      <input type="text" class="form-control is-valid" id="validationServer01" value="Mark" required>
      <div class="valid-feedback">
        Looks good!
      </div>
    </div>
    <div class="col-sm-6 mb-3">
      <label for="validationServer02">Last name</label>
      <input type="text" class="form-control is-valid" id="validationServer02" value="Otto" required>
      <div class="valid-feedback">
        Looks good!
      </div>
    </div>
  </div>
  <div class="form-row">
    <div class="col-sm-5 mb-3">
      <label for="validationServer03">City</label>
      <input type="text" class="form-control is-invalid" id="validationServer03" required>
      <div class="invalid-feedback">
        Please provide a valid city.
      </div>
    </div>
    <div class="col-sm-4 mb-3">
      <label for="validationServer04">Province</label>
      <input type="text" class="form-control is-invalid" id="validationServer04" required>
      <div class="invalid-feedback">
        Please provide a valid province.
      </div>
    </div>
    <div class="col-sm-3 col-6 mb-3">
      <label for="validationServer05">Postal code</label>
      <input type="text" class="form-control is-invalid" id="validationServer05" required>
      <div class="invalid-feedback">
        Please provide a valid postal code.
      </div>
    </div>
  </div>
  <div class="form-group">
    <div class="custom-control custom-checkbox">
      <input type="checkbox" class="custom-control-input is-invalid" value="" id="invalidCheck3" required>
      <label class="custom-control-label" for="invalidCheck3">
        Agree to terms and conditions
      </label>
      <div class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <button class="btn btn-primary" type="submit">Submit form</button>
</form>

Validation classes .is-invalid and .is-valid can be toggled with JQuery when there is a change to a field, and when the form is submitted.

  • Required fields will use the togglevalid() function below to ensure the appropriate class is defined in the field.
  • Optional fields which allow any format will not require JQuery to toggle classes, since these fields are always valid.
  • Optional fields which require a defined format when they are entered, for example an optional phone number field, will use the toggleavalidoptional() function.

For example, you may have a form with three fields:

  • Name (optional) - any text allowed
  • Phone Number (optional) - if entered must be in format 000-000-0000
  • Email Address - this is a required field
<script type="text/javascript">
  function togglevalid(ID) {
    if ($('#' + ID).valid()) { $('#' + ID).removeClass('is-invalid'); $('#' + ID).addClass('is-valid'); }
    else { $('#' + ID).removeClass('is-valid'); $('#' + ID).addClass('is-invalid'); }
  }

  function togglevalidoptional(ID) {
    if ($('#' + ID).valid()) { $('#' + ID).removeClass('is-invalid'); }
    else { $('#' + ID).addClass('is-invalid'); }
  }

  $('#PhoneNumber').change(function () { togglevalidoptional('PhoneNumber'); });
  $('#EmailAddress').change(function () { togglevalid('EmailAddress'); });

  $(function () {
    $('form').submit(function () {
      togglevalidoptional('PhoneNumber');
      togglevalid('EmailAddress');
    });
  });
</script>

Supported elements

Validation styles are available for the following included form controls and components:

  • <input>s and <textarea>s with .form-control (including up to one .form-control in input groups)
  • <select>s with .custom-select
  • .custom-checkboxs and .custom-radios
Please enter a message in the textarea.
Example invalid feedback text
More example invalid feedback text
Example invalid custom select feedback
<form class="was-validated">
  <div class="form-group">
    <label for="validationTextarea">Textarea</label>
    <textarea class="form-control" id="validationTextarea" required></textarea>
    <div class="invalid-feedback">
      Please enter a message in the textarea.
    </div>
  </div>
  
  <div class="custom-control custom-checkbox mb-3">
    <input type="checkbox" class="custom-control-input" id="customControlValidation1" required>
    <label class="custom-control-label" for="customControlValidation1">Check this custom checkbox</label>
    <div class="invalid-feedback">Example invalid feedback text</div>
  </div>

  <div class="custom-control custom-radio">
    <input type="radio" class="custom-control-input" id="customControlValidation2" name="radio-stacked" required>
    <label class="custom-control-label" for="customControlValidation2">Toggle this custom radio</label>
  </div>
  <div class="custom-control custom-radio mb-3">
    <input type="radio" class="custom-control-input" id="customControlValidation3" name="radio-stacked" required>
    <label class="custom-control-label" for="customControlValidation3">Or toggle this other custom radio</label>
    <div class="invalid-feedback">More example invalid feedback text</div>
  </div>

  <div class="form-row">
    <div class="col-sm-5">
      <div class="form-group">
        <label for="selectRequired">Select an option</label>
        <select id="selectRequired" class="custom-select" required>
          <option value="">Open this select menu</option>
          <option value="1">One</option>
          <option value="2">Two</option>
          <option value="3">Three</option>
        </select>
        <div class="invalid-feedback">Example invalid custom select feedback</div>
      </div>
    </div>
  </div>

</form>

Customizing

Validation states can be customized via Sass with the $form-validation-states map. Located in our _variables.scss file, this Sass map is looped over to generate the default valid/invalid validation states. Included is a nested map for customizing each state’s colour and icon. While no other states are supported by browsers, those using custom styles can easily add more complex form feedback.

Please note that we do not recommend customizing these values without also modifying the form-validation-state mixin.

// Sass map from `_variables.scss`
// Override this and recompile your Sass to generate different states
$form-validation-states: map-merge(
  (
    "valid": (
      "color": $form-feedback-valid-color,
      "icon": $form-feedback-icon-valid
    ),
    "invalid": (
      "color": $form-feedback-invalid-color,
      "icon": $form-feedback-icon-invalid
    )
  ),
  $form-validation-states
);

// Loop from `_forms.scss`
// Any modifications to the above Sass map will be reflected in your compiled
// CSS via this loop.
@each $state, $data in $form-validation-states {
  @include form-validation-state($state, map-get($data, color), map-get($data, icon));
}