|

Validation

With HTML5 form validation, through browser default behaviors or custom styles, and JavaScript, give the consumers useful, actionable feedback.

CAUTION

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 is how UX4G handles form validation:

  • The two pseudo-classes :invalid and:valid in CSS are used to provide HTML form validation. It applies to the <textarea>, <select>, and <input> components.
  • The :invalid and :valid styles in UX4G are scoped to the parent class, which is typically applied to the <form>. Without a value, any necessary field displays as invalid when the page loads. This gives developer the option to decide when to activate them (usually following a failed form submission).
  • For server-side validation, the .is-invalid and .is-valid classes can be used as a backup to the pseudo-classes. They don't need a parent class that has been validated by .was.
  • It is not possible (at the moment) to apply styles to a <label> that appears before a form control in the DOM without the use of specialized JavaScript due to CSS limitations.
  • The constraint validation API, a collection of JavaScript methods for validating form controls, is supported by all current browsers. Browser-defaults
  • The defaults for each browser, which are not styleable with CSS, may be used in feedback messages, or create the own feedback styles using additional HTML and CSS.
  • With JavaScript's setCustomValidity method, you may offer unique validity messages.

Custom styles #

Must include the novalidate boolean element in your <form> in order to receive custom UX4G form validation messages. While the built-in feedback tooltips of the browser are disabled, JavaScript's form validation APIs are still available. If trying to submit the form below, the JavaScript will catch it and send the feedback. The form controls will have the :invalid and :valid styles applied when you try to submit.

To improve feedback communication, users can apply custom colors, borders, focus styles, and backdrop icons. Only with are background icons for "select"s accessible .instead of .form-control, use form-select.

<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4">
    <label for="validationCustom01" class="form-label">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">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">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">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">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">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" type="submit">Submit form</button>
  </div>
</form>
RESULT
Looks good!
Looks good!
@
Please choose a username.
Please provide a valid city.
Please select a valid state.
Please provide a valid zip.
You must agree before submitting.
// Example starter JavaScript for disabling form submissions if there are invalid fields
(() => {
  'use strict'

  // Fetch all the forms we want to apply custom UX4G 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 #

Don't want to create unique validation feedback messages or modify form behavior using JavaScript? All Good, can use the browser's default settings. Consider sending the form below. You'll notice a somewhat varied form of feedback depending on your browser and operating system.

Although CSS cannot be used to style these feedback styles, JavaScript can still be used to alter the feedback text.

<form class="row g-3">
  <div class="col-md-4">
    <label for="validationDefault01" class="form-label">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">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">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">City</label>
    <input type="text" class="form-control" id="validationDefault03" required/>
  </div>
  <div class="col-md-3">
    <label for="validationDefault04" class="form-label">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">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" type="submit">Submit form</button>
  </div>
</form>
RESULT
@

Server side #

Although server-side validation is not advised, can indicate which form fields are invalid and valid using the .is-invalid and .is-valid directives. Keep in mind that these classes also support .invalid-feedback.

Use the aria-describedby attribute to link the invalid feedback or error message to the appropriate form field in the case of invalid fields (note that this feature permits more than one id to be referenced, in the event that the field already connects to extra form text).

Input groups need an additional .has-validation class to address border radius problems.

<form class="row g-3">
  <div class="col-md-4">
        <label for="validationServer0" class="form-label">Warning</label><input type="text" class="form-control is-warning" id="validationServer0" required="" value="Mark" />
        <div class="warning-feedback">
         <i class="fa fa-engine-warning"></i> Enter valid inputs</div>
    </div>
    <div class="col-md-4">
        <label for="validationServer01" class="form-label">First name</label><input type="text" class="form-control is-valid" id="validationServer01" required="" value="Mark" />
        <div class="valid-feedback">  <i class="fa fa-check-circle"></i> Looks good!</div>
    </div>
    <div class="col-md-4">
        <label for="validationServer02" class="form-label">Last name</label><input type="text" class="form-control is-valid" id="validationServer02" required="" value="Otto" />
        <div class="valid-feedback">Looks good!</div>
    </div>
    <div class="col-md-6">
        <label for="validationServerUsername" class="form-label">Username</label>
        <div class="input-group has-validation">            
            <input type="text" class="form-control is-invalid" id="validationServerUsername" aria-describedby="inputGroupPrepend3 validationServerUsernameFeedback" required="" />
            <div id="validationServerUsernameFeedback" class="invalid-feedback"><i class="fa fa-info-circle"></i> Please choose a username.</div>
        </div>
    </div>
    <div class="col-md-6">
        <label for="validationServer03" class="form-label">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-6">
        <label for="validationServer04" class="form-label">State</label>
        <select class="form-select is-invalid" id="validationServer04" aria-describedby="validationServer04Feedback" required="">
            <option disabled="" value="">Choose...</option>
            <option>...</option>
        </select>
        <div id="validationServer04Feedback" class="invalid-feedback">Please select a valid state.</div>
    </div>
    <div class="col-md-6">
        <label for="validationServer05" class="form-label">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" id="invalidCheck3" aria-describedby="invalidCheck3Feedback" required="" value="" />
            <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" type="submit">Submit form</button></div>
</form>
RESULT
Enter valid inputs
Looks good!
Looks good!
Please choose a username.
Please provide a valid city.
Please select a valid state.
Please provide a valid zip.
You must agree before submitting.

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
<form class="was-validated">
  <div class="mb-3">
    <label for="validationTextarea" class="form-label">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">
    <button class="btn btn-primary" type="submit" disabled>Submit form</button>
  </div>
</form>
RESULT
Please enter a message in the textarea.
Example invalid feedback text
More example invalid feedback text
Example invalid select feedback
Example invalid form file feedback

Tooltips #

If the form's layout permits it, then swap the feedback classes that are {valid | invalid}. Validation feedback can be shown as a tooltip using the {valid | invalid}-tooltip classes. For tooltip placement, make sure your parent has the property position: relative set. Although this is already included in the example below thanks to the column classes, the project might call for a different configuration.

<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4 position-relative">
    <label for="validationTooltip01" class="form-label">First name</label>
    <input type="text" class="form-control" id="validationTooltip01" value="Mark" required/ >
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="validationTooltip02" class="form-label">Last name</label>
    <input type="text" class="form-control" id="validationTooltip02" value="Otto" required/ >
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="validationTooltipUsername" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="validationTooltipUsernamePrepend">@</span>
      <input type="text" class="form-control" id="validationTooltipUsername" aria-describedby="validationTooltipUsernamePrepend" required/  >
      <div class="invalid-tooltip">
        Please choose a unique and valid username.
      </div>
    </div>
  </div>
  <div class="col-md-6 position-relative">
    <label for="validationTooltip03" class="form-label">City</label>
    <input type="text" class="form-control" id="validationTooltip03" required/  >
    <div class="invalid-tooltip">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3 position-relative">
    <label for="validationTooltip04" class="form-label">State</label>
    <select class="form-select" id="validationTooltip04" required>
      <option selected disabled value="">Choose...</option>
      <option>...</option>
    </select>   
    <div class="invalid-tooltip">
      Please select a valid state.
    </div>
  </div>
  <div class="col-md-3 position-relative">
    <label for="validationTooltip05" class="form-label">Zip</label>
    <input type="text" class="form-control" id="validationTooltip05" required/  >
    <div class="invalid-tooltip">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>
RESULT
Looks good!
Looks good!
@
Please choose a unique and valid username.
Please provide a valid city.
Please select a valid state.
Please provide a valid zip.

Sass #

Variables #

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

$form-feedback-icon-valid-color:    $form-feedback-valid-color;
$form-feedback-icon-valid:          url("data:image/svg+xml,");
$form-feedback-icon-invalid-color:  $form-feedback-invalid-color;
$form-feedback-icon-invalid:        url("data:image/svg+xml,");

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;
    }
  }
}

@mixin form-validation-state(
  $state,
  $color,
  $icon,
  $tooltip-color: color-contrast($color),
  $tooltip-bg-color: rgba($color, $form-feedback-tooltip-opacity),
  $focus-box-shadow: 0 0 $input-btn-focus-blur $input-focus-width rgba($color, $input-btn-focus-color-opacity)
) {
  .#{$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;
    color: $color;
  }

  .#{$state}-tooltip {
    position: absolute;
    top: 100%;
    z-index: 5;
    display: none;
    max-width: 100%; // Contain to parent when possible
    padding: $form-feedback-tooltip-padding-y $form-feedback-tooltip-padding-x;
    margin-top: .1rem;
    @include font-size($form-feedback-tooltip-font-size);
    line-height: $form-feedback-tooltip-line-height;
    color: $tooltip-color;
    background-color: $tooltip-bg-color;
    @include border-radius($form-feedback-tooltip-border-radius);
  }

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

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

      @if $enable-validation-icons {
        padding-right: $input-height-inner;
        background-image: escape-svg($icon);
        background-repeat: no-repeat;
        background-position: right $input-height-inner-quarter center;
        background-size: $input-height-inner-half $input-height-inner-half;
      }

      &:focus {
        border-color: $color;
        box-shadow: $focus-box-shadow;
      }
    }
  }

  // stylelint-disable-next-line selector-no-qualifying-type
  textarea.form-control {
    @include form-validation-state-selector($state) {
      @if $enable-validation-icons {
        padding-right: $input-height-inner;
        background-position: top $input-height-inner-quarter right $input-height-inner-quarter;
      }
    }
  }

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

      @if $enable-validation-icons {
        &: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;
        }
      }

      &:focus {
        border-color: $color;
        box-shadow: $focus-box-shadow;
      }
    }
  }

  .form-control-color {
    @include form-validation-state-selector($state) {
      @if $enable-validation-icons {
        width: add($form-color-width, $input-height-inner);
      }
    }
  }

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

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

      &:focus {
        box-shadow: $focus-box-shadow;
      }

      ~ .form-check-label {
        color: $color;
      }
    }
  }
  .form-check-inline .form-check-input {
    ~ .#{$state}-feedback {
      margin-left: .5em;
    }
  }

  .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 tooltips and focus styles.

Loop #

Used to create the validation styles by iterating over the variables in the $form-validation-states map. Through this loop, any changes to the aforementioned Sass map will be reflected in the produced CSS.

@each $state, $data in $form-validation-states {
@include form-validation-state($state, $data...);
}

Customizing #

The $form-validation-states map in Sass allows for the customization of validation stages. This Sass map, which can be found in the _variables.scss file, to create the default valid/invalid validation states. The color, icon, tooltip color, and focus shadow of each state can be altered using the included nested map. Browsers do not support any further states, however users of custom styles can simply provide more complicated form feedback.