View on GitHub

Validation

Provide valuable, actionable feedback to your users with HTML5 form validation, via browser default behaviors or custom styles and JavaScript.

On this page

We are aware that currently the client-side custom validation styles and tooltips are not accessible, since they are not exposed to assistive technologies. While we work on a solution, we’d recommend either using the server-side option or the default browser validation method.

How it works

Here’s how form validation works with Boosted:

HTML form validation is applied via CSS’s two pseudo-classes, :invalid and :valid. It applies to <input>, <select>, and <textarea> elements.
Boosted 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 Boosted 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 colors, borders, focus styles, and background icons to better communicate feedback. Background icons for <select>s are only available with .form-select, and not .form-control.

html

<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4">
    <label for="validationCustom01" class="form-label is-required">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-md-4">
    <label for="validationCustom02" class="form-label is-required">Last name</label>
    <input type="text" class="form-control" id="validationCustom02" value="Otto" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="validationCustomUsername" class="form-label is-required">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="inputGroupPrepend">@</span>
      <input type="text" class="form-control" id="validationCustomUsername" aria-describedby="inputGroupPrepend" required>
      <div class="invalid-feedback">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationCustom03" class="form-label is-required">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-md-3">
    <label for="validationCustom04" class="form-label is-required">State</label>
    <select class="form-select" id="validationCustom04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
    <div class="invalid-feedback">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationCustom05" class="form-label is-required">Zip</label>
    <input type="text" class="form-control" id="validationCustom05" required>
    <div class="invalid-feedback">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input" type="checkbox" value="" id="invalidCheck" required>
      <label class="form-check-label" for="invalidCheck">
        Agree to terms and conditions
      </label>
      <div class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary mt-2" type="submit">Submit form</button>
  </div>
</form>

// Example starter JavaScript for disabling form submissions if there are invalid fields
(() => {
  'use strict'

  // Fetch all the forms we want to apply custom Bootstrap validation styles to
  const forms = document.querySelectorAll('.needs-validation')

  // Loop over them and prevent submission
  Array.from(forms).forEach(form => {
    form.addEventListener('submit', event => {
      if (!form.checkValidity()) {
        event.preventDefault()
        event.stopPropagation()
      }

      form.classList.add('was-validated')
    }, false)
  })
})()

Browser defaults

Not interested in custom validation feedback messages or writing JavaScript to change form behaviors? 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.

html

<form class="row g-3">
  <div class="col-md-4">
    <label for="validationDefault01" class="form-label is-required">First name</label>
    <input type="text" class="form-control" id="validationDefault01" value="Mark" required>
  </div>
  <div class="col-md-4">
    <label for="validationDefault02" class="form-label is-required">Last name</label>
    <input type="text" class="form-control" id="validationDefault02" value="Otto" required>
  </div>
  <div class="col-md-4">
    <label for="validationDefaultUsername" class="form-label is-required">Username</label>
    <div class="input-group">
      <span class="input-group-text" id="inputGroupPrepend2">@</span>
      <input type="text" class="form-control" id="validationDefaultUsername" aria-describedby="inputGroupPrepend2" required>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationDefault03" class="form-label is-required">City</label>
    <input type="text" class="form-control" id="validationDefault03" required>
  </div>
  <div class="col-md-3">
    <label for="validationDefault04" class="form-label is-required">State</label>
    <select class="form-select" id="validationDefault04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
  </div>
  <div class="col-md-3">
    <label for="validationDefault05" class="form-label is-required">Zip</label>
    <input type="text" class="form-control" id="validationDefault05" required>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input" type="checkbox" value="" id="invalidCheck2" required>
      <label class="form-check-label" for="invalidCheck2">
        Agree to terms and conditions
      </label>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary mt-2" type="submit">Submit form</button>
  </div>
</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.

For invalid fields, ensure that the invalid feedback/error message is associated with the relevant form field using aria-describedby (noting that this attribute allows more than one id to be referenced, in case the field already points to additional form text).

To fix issues with border radius, input groups require an additional .has-validation class.

html

<form class="row g-3">
  <div class="col-md-4">
    <label for="validationServer01" class="form-label is-required">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-md-4">
    <label for="validationServer02" class="form-label is-required">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 class="col-md-4">
    <label for="validationServerUsername" class="form-label is-required">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="inputGroupPrepend3">@</span>
      <input type="text" class="form-control is-invalid" id="validationServerUsername" aria-describedby="inputGroupPrepend3 validationServerUsernameFeedback" required>
      <div id="validationServerUsernameFeedback" class="invalid-feedback">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <label for="validationServer03" class="form-label is-required">City</label>
    <input type="text" class="form-control is-invalid" id="validationServer03" aria-describedby="validationServer03Feedback" required>
    <div id="validationServer03Feedback" class="invalid-feedback">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationServer04" class="form-label is-required">State</label>
    <select class="form-select is-invalid" id="validationServer04" aria-describedby="validationServer04Feedback" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>
    <div id="validationServer04Feedback" class="invalid-feedback">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3">
    <label for="validationServer05" class="form-label is-required">Zip</label>
    <input type="text" class="form-control is-invalid" id="validationServer05" aria-describedby="validationServer05Feedback" required>
    <div id="validationServer05Feedback" class="invalid-feedback">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <div class="form-check">
      <input class="form-check-input is-invalid" type="checkbox" value="" id="invalidCheck3" aria-describedby="invalidCheck3Feedback" required>
      <label class="form-check-label" for="invalidCheck3">
        Agree to terms and conditions
      </label>
      <div id="invalidCheck3Feedback" class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary mt-2" type="submit">Submit form</button>
  </div>
</form>

Supported elements

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

<input>s and <textarea>s with .form-control (including up to one .form-control in input groups)
<select>s with .form-select
.form-checks

html

<form class="was-validated">
  <div class="mb-3">
    <label for="validationTextarea" class="form-label is-required">Textarea</label>
    <textarea class="form-control" id="validationTextarea" placeholder="Required example textarea" required></textarea>
    <div class="invalid-feedback">
      Please enter a message in the textarea.
    </div>
  </div>

  <div class="form-check mb-3">
    <input type="checkbox" class="form-check-input" id="validationFormCheck1" required>
    <label class="form-check-label" for="validationFormCheck1">Check this checkbox</label>
    <div class="invalid-feedback">Example invalid feedback text</div>
  </div>

  <div class="form-check">
    <input type="radio" class="form-check-input" id="validationFormCheck2" name="radio-stacked" required>
    <label class="form-check-label" for="validationFormCheck2">Toggle this radio</label>
  </div>
  <div class="form-check mb-3">
    <input type="radio" class="form-check-input" id="validationFormCheck3" name="radio-stacked" required>
    <label class="form-check-label" for="validationFormCheck3">Or toggle this other radio</label>
    <div class="invalid-feedback">More example invalid feedback text</div>
  </div>

  <div class="mb-3">
    <select class="form-select" required aria-label="select example">
      <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 select feedback</div>
  </div>

  <div class="mb-3">
    <input type="file" class="form-control" aria-label="file example" required>
    <div class="invalid-feedback">Example invalid form file feedback</div>
  </div>

  <div class="mb-3">
    <label for="inputQuantitySelector" class="form-label">Quantity selector</label>
    <div class="input-group quantity-selector w-100">
      <input type="number" id="inputQuantitySelector" class="form-control" aria-live="polite" data-bs-step="counter" name="quantity" title="quantity" value="11" min="0" max="10" step="1" data-bs-round="0" aria-label="Quantity selector">
      <button type="button" class="btn btn-icon btn-secondary" aria-describedby="inputQuantitySelector" data-bs-step="down">
        <span class="visually-hidden">Step down</span>
      </button>
      <button type="button" class="btn btn-icon btn-secondary" aria-describedby="inputQuantitySelector" data-bs-step="up">
        <span class="visually-hidden">Step up</span>
      </button>
      <div class="invalid-feedback">Please enter a valid number.</div>
    </div>
  </div>

  <div class="mb-3">
    <button class="btn btn-primary mt-2" type="submit" disabled>Submit form</button>
  </div>
</form>

Sass

Variables

$form-feedback-margin-top:          $form-text-margin-top;
$form-feedback-font-size:           $small-font-size;
$form-feedback-font-style:          null;
$form-feedback-valid-color:         $success;
$form-feedback-invalid-color:       $danger;

$form-feedback-icon-valid:          var(--#{$boosted-prefix}success-icon);
$form-feedback-icon-invalid:        var(--#{$boosted-prefix}error-icon);
$form-feedback-icon-size:           add($spacer * .25, $spacer * .5); // Boosted mod
$form-feedback-line-height:         $line-height-sm; // Boosted mod

Mixins

Two mixins are combined together, through our loop, to generate our form validation feedback styles.

@mixin form-validation-state-selector($state) {
  @if ($state == "valid" or $state == "invalid") {
    .was-validated #{if(&, "&", "")}:#{$state},
    #{if(&, "&", "")}.is-#{$state} {
      @content;
    }
  } @else {
    #{if(&, "&", "")}.is-#{$state} {
      @content;
    }
  }
}

// Boosted mod: no .#{$state}-tooltip, so no need for `$tooltip-*` args
@mixin form-validation-state($state, $color, $icon) {
  // Boosted mod: valid ≠ invalid
  @if $state == "valid" {
    .#{$state}-feedback {
      display: none;
      @extend .visually-hidden; // Boosted mod: Do not visually display .valid-feedback
    }

    @if $enable-validation-icons {
      :not(.quantity-selector) > .form-control {
        @include form-validation-state-selector($state) {
          padding-right: $input-height-inner;
          background-image: escape-svg($icon);
          background-repeat: no-repeat;
          background-position: right $input-height-inner-quarter top subtract($input-height-inner-quarter, 2px);
          background-size: $input-height-inner-half $input-height-inner-half;
        }
      }

      .form-select {
        @include form-validation-state-selector($state) {
          &:not([multiple]):not([size]),
          &:not([multiple])[size="1"] {
            padding-right: $form-select-feedback-icon-padding-end;
            background-image: escape-svg($form-select-indicator), escape-svg($icon);
            background-position: $form-select-bg-position, $form-select-feedback-icon-position;
            background-size: $form-select-bg-size, $form-select-feedback-icon-size;
          }
        }
      }

      .form-control-color {
        @include form-validation-state-selector($state) {
          width: add($form-color-width, $input-height-inner);
        }
      }
    }
  } @else {
    .#{$state}-feedback {
      display: none;
      width: 100%;
      margin-top: $form-feedback-margin-top;
      @include font-size($form-feedback-font-size);
      font-style: $form-feedback-font-style;
      font-weight: $font-weight-bold; // Boosted mod
      line-height: $form-feedback-line-height; // Boosted mod

      // Boosted mod: status should not rely on color only
      @if $enable-validation-icons {
        &::before {
          flex-shrink: 0;
          align-self: center;
          width: $form-feedback-icon-size;
          height: $form-feedback-icon-size;
          margin-right: map-get($spacers, 1);
          content: "";
          background: $form-feedback-icon-invalid no-repeat;
        }
      }
    }

    // Boosted mod: no .#{$state}-tooltip

    @include form-validation-state-selector($state) {
      ~ .#{$state}-feedback,
      ~ .#{$state}-tooltip {
        display: flex; // Boosted mod
      }
    }

    .form-control {
      @include form-validation-state-selector($state) {
        border-color: $color;

        // Boosted mod: validation icon in .*-feedback

        // Boosted mod: no box-shadow

        // Boosted mod: focus styles don't match validation state
      }
    }

    // Boosted mod: Remove border on input for form element QuantitySelector
    .quantity-selector .form-control {
      @include form-validation-state-selector($state) {
        border-right: none;
        border-left: none;

        // stylelint-disable-next-line scss/selector-no-redundant-nesting-selector
        & ~ button {
          border-color: $color;
        }
      }
    }
    // End mod

    // Boosted mod: no icon in background for textarea

    .form-select {
      @include form-validation-state-selector($state) {
        border-color: $color;

        // Boosted mod: no icon in background

        // Boosted mod: no box-shadow

        // Boosted mod: focus styles don't match validation state
      }
    }

    .form-check-input {
      @include form-validation-state-selector($state) {
        filter: none; // Boosted mod: remove filter to avoid having a blue border (invert of red border)
        border-color: $color;

        &:checked,
        &:active {
          background-color: $color;
        }

        // Boosted mod: no box-shadow

        // Boosted mod: label's color doesn't change
      }
    }
    .form-check-inline .form-check-input {
      ~ .#{$state}-feedback {
        margin-left: .5em;
      }
    }
  }
  // End mod
  .input-group {
    > .form-control:not(:focus),
    > .form-select:not(:focus),
    > .form-floating:not(:focus-within) {
      @include form-validation-state-selector($state) {
        @if $state == "valid" {
          z-index: 3;
        } @else if $state == "invalid" {
          z-index: 4;
        }
      }
    }
  }
}

Map

This is the validation Sass map from _variables.scss. Override or extend this to generate different or additional states.

$form-validation-states: (
  "valid": (
    "color": $form-feedback-valid-color,
    "icon": $form-feedback-icon-valid
  ),
  "invalid": (
    "color": $form-feedback-invalid-color,
    "icon": $form-feedback-icon-invalid
  )
);

Maps of $form-validation-states can contain three optional parameters to override focus styles.

Loop

Used to iterate over $form-validation-states map values to generate our validation styles. 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, $data...);
}

Customizing

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