Form validation

How it works #

Here's how form validation works with Halfmoon:

• HTML form validation is applied via CSS's two pseudo-classes, :invalid and :valid. It applies to <input>, <select>, and <textarea> elements.
• Halfmoon 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 (opens in new tab), 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 Halfmoon 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> elements are only available with .form-select, and not .form-control.

<!-- Custom styles form validation -->
<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4">
    <label for="1-fname" class="form-label">First name</label>
    <input type="text" class="form-control" id="1-fname" placeholder="First name" value="Steve" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="1-lname" class="form-label">Last name</label>
    <input type="text" class="form-control" id="1-lname" placeholder="Last name" value="Jobs" required>
    <div class="valid-feedback">
      Looks good!
    </div>
  </div>
  <div class="col-md-4">
    <label for="1-username" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="1-username-prepend">@</span>
      <input type="text" class="form-control" id="1-username" aria-describedby="1-username-prepend" placeholder="Username" required>
      <div class="invalid-feedback">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <label for="1-city" class="form-label">City</label>
    <input type="text" class="form-control" id="1-city" placeholder="Your city" required>
    <div class="invalid-feedback">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3">
    <label for="1-state" class="form-label">State</label>
    <select class="form-select" id="1-state" 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="1-zip" class="form-label">Zip</label>
    <input type="text" class="form-control" id="1-zip" placeholder="Zip code" 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="1-agree-toc" required>
      <label class="form-check-label" for="1-agree-toc">
        Agree to terms and conditions
      </label>
      <div class="invalid-feedback">
        You must agree before submitting.
      </div>
    </div>
  </div>
  <div class="col-12 text-end">
    <button class="btn btn-primary" 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 Halfmoon 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.

<!-- Browser defaults form validation -->
<form class="specific-w-300 mw-100 mx-auto">
  <div class="row g-3 mb-3">
    <div class="col-6">
      <label for="2-fname" class="form-label">First name</label>
      <input type="text" class="form-control" id="2-fname" placeholder="First name" value="Steve" required>
    </div>
    <div class="col-6">
      <label for="2-lname" class="form-label">Last name</label>
      <input type="text" class="form-control" id="2-lname" placeholder="Last name" required>
    </div>
    <div class="col-12">
      <label for="2-username" class="form-label">Username</label>
      <div class="input-group">
        <span class="input-group-text" id="2-username-prepend">@</span>
        <input type="text" class="form-control" id="2-username" aria-describedby="2-username-prepend" placeholder="Username" required minlength="6" maxlength="40">
      </div>
    </div>
    <div class="col-12">
      <button type="submit" class="btn btn-primary w-100">Set password</button>
    </div>
  </div>
  <div class="text-center text-body-secondary pt-3 border-top">
    Already have an account? <a href="#">Sign in</a>
  </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).

<!-- Server-side form validation -->
<form class="specific-w-300 mw-100 mx-auto">
  <div class="row g-3 mb-3">
    <div class="col-6">
      <label for="3-fname" class="form-label">First name</label>
      <input type="text" class="form-control is-valid" id="3-fname" placeholder="First name" value="Steve" required>
      <div class="valid-feedback">
        Looks good!
      </div>
    </div>
    <div class="col-6">
      <label for="3-lname" class="form-label">Last name</label>
      <input type="text" class="form-control is-invalid" id="3-lname" placeholder="Last name" required aria-describedby="3-lname-invalid-feedback">
      <div class="invalid-feedback" id="3-lname-invalid-feedback">
        This is required.
      </div>
    </div>
    <div class="col-12">
      <label for="3-username" class="form-label">Username</label>
      <div class="input-group has-validation">
        <span class="input-group-text" id="3-username-prepend">@</span>
        <input type="text" class="form-control is-invalid" id="3-username" aria-describedby="3-username-prepend 3-username-invalid-feedback" placeholder="Username" required minlength="6" maxlength="40">
        <div class="invalid-feedback" id="3-username-invalid-feedback">
          Please choose a username, 6 - 40 characters.
        </div>
      </div>
    </div>
    <div class="col-12">
      <button type="submit" class="btn btn-primary w-100">Set password</button>
    </div>
  </div>
  <div class="text-center text-body-secondary pt-3 border-top">
    Already have an account? <a href="#">Sign in</a>
  </div>
</form>

Supported elements #

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

• <input> and <textarea> elements with .form-control (including file input, and up to one .form-control in input groups)
• <select> elements with .form-select
• .form-check components, such as checkboxes, radio buttons, and switches

The examples above do a good job of showcasing most of what's available. The example below shows a <textarea> and a file input with validation styles.

<!-- Textarea and file input validation -->
<form class="was-validated specific-w-300 mw-100 mx-auto">
  <div class="mb-3">
    <label for="4-description" class="form-label">Description</label>
    <textarea class="form-control" id="4-description" placeholder="Why are you the right fit?" required></textarea>
    <div class="invalid-feedback">
      Please tell us why you want to join us.
    </div>
  </div>
  <div class="mb-3">
    <label for="4-cv" class="form-label">Attach your CV</label>
    <input type="file" class="form-control" id="4-cv" required>
    <div class="invalid-feedback">
      Your updated CV is required.
    </div>
  </div>
  <div class="text-end border-top pt-3">
    <button class="btn btn-primary w-100" type="submit" disabled>Apply for position</button>
  </div>
</form>

Here's another example of validation styles being used on radio buttons (along with a slightly different design for the form). In this case, the feedback is added inside the last .form-check container.

<!-- Radio buttons validation -->
<div class="card specific-w-300 mw-100 mx-auto">
  <div class="card-body">
    <form class="was-validated">
      <label class="form-label">What is your specialization?</label>
      <div class="form-check">
        <input class="form-check-input" type="radio" value="marketing" name="radio-group-1" id="5-marketing" required>
        <label class="form-check-label" for="5-marketing">Marketing</label>
      </div>
      <div class="form-check mb-3">
        <input class="form-check-input" type="radio" value="product-design" name="radio-group-1" id="5-product-design" required>
        <label class="form-check-label" for="5-product-design">Product design</label>
        <div class="invalid-feedback">
          Please select your specialization.
        </div>
      </div>
      <div class="d-flex justify-content-between">
        <a href="#" class="btn btn-secondary">Go back</a>
        <button type="submit" class="btn btn-primary">Submit</button>
      </div>
    </form>
  </div>
</div>

Tooltips #

If your form layout allows it, you can swap the .{valid|invalid}-feedback classes for .{valid|invalid}-tooltip classes to display validation feedback in a styled tooltip. Be sure to have a parent with position: relative on it for tooltip positioning. In the example below, our column classes have this already, but your project may require an alternative setup.

<!-- Tooltips form validation -->
<form class="row g-3 needs-validation" novalidate>
  <div class="col-md-4 position-relative">
    <label for="6-fname" class="form-label">First name</label>
    <input type="text" class="form-control" id="6-fname" placeholder="First name" value="Steve" required>
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="6-lname" class="form-label">Last name</label>
    <input type="text" class="form-control" id="6-lname" placeholder="Last name" value="Jobs" required>
    <div class="valid-tooltip">
      Looks good!
    </div>
  </div>
  <div class="col-md-4 position-relative">
    <label for="6-username" class="form-label">Username</label>
    <div class="input-group has-validation">
      <span class="input-group-text" id="6-username-prepend">@</span>
      <input type="text" class="form-control" id="6-username" aria-describedby="6-username-prepend" placeholder="Username" required>
      <div class="invalid-tooltip">
        Please choose a username.
      </div>
    </div>
  </div>
  <div class="col-md-6 position-relative">
    <label for="6-city" class="form-label">City</label>
    <input type="text" class="form-control" id="6-city" placeholder="Your city" required>
    <div class="invalid-tooltip">
      Please provide a valid city.
    </div>
  </div>
  <div class="col-md-3 position-relative">
    <label for="6-state" class="form-label">State</label>
    <select class="form-select" id="6-state" 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="6-zip" class="form-label">Zip</label>
    <input type="text" class="form-control" id="6-zip" placeholder="Zip code" required>
    <div class="invalid-tooltip">
      Please provide a valid zip.
    </div>
  </div>
  <div class="col-12 text-end">
    <button class="btn btn-primary" type="submit">Submit form</button>
  </div>
</form>