HTML Constraint Validation API: Complete Guide with Examples

Form validation is a cornerstone of user-friendly web development. While HTML5 provides basic built-in validation, the HTML Constraint Validation API gives developers surgical control over error messages, validation timing, and error handling — all without a single external library or backend round-trip.

This guide walks through every feature of the API with working code examples, so you can implement it confidently today.

Table of Contents

• Why Use the HTML Constraint Validation API?
• 1. HTML5 Validation Attributes — The Foundation
• 2. checkValidity() and reportValidity()
• 3. Custom Error Messages with setCustomValidity()
• 4. The validity Property — Pinpoint the Exact Error
• 5. The willValidate Property
• Live CodePen Demo
• Comparison: Default vs. API Validation
• Best Practices
• Conclusion

Why Use the HTML Constraint Validation API?

HTML5 introduced attributes like required, pattern, and type for validation — but they have real limits. Error messages are browser-generated and often vague. Validation fires automatically on submit, giving you no control over timing.

The Constraint Validation API solves all of this:

• Customizable feedback — replace generic browser messages with helpful, specific prompts
• Controlled timing — validate on blur, on input, or only at submission
• Granular error detection — know exactly why an input failed, not just that it did

1. HTML5 Validation Attributes — The Foundation

Before reaching for JavaScript, HTML5 attributes give you a free validation baseline:

These attributes work hand-in-hand with the API — they define the constraints; the API lets you control and customize how those constraints are reported.

2. checkValidity() and reportValidity()

These two methods are the core of the API:

• checkValidity() — returns true if all constraints pass, false if any fail. Silent — no UI shown.
• reportValidity() — same check, but also triggers browser error UI for any failing fields.

Call them on either an individual input or the entire <form> element.

const form = document.querySelector("form");

form.addEventListener("submit", (event) => {
  if (!form.checkValidity()) {
    event.preventDefault(); // stop submission
    form.reportValidity();  // show built-in messages
  }
});

Why this matters: adding novalidate to your <form> tag disables the browser’s automatic validation on submit, putting you fully in control of when and how feedback appears.

3. Custom Error Messages with setCustomValidity()

This is the API’s most used feature. Pass a non-empty string to show a custom error; pass an empty string to clear it.

const emailInput = document.querySelector("input[type='email']");

emailInput.addEventListener("input", () => {
  if (emailInput.validity.typeMismatch) {
    emailInput.setCustomValidity(
      "Please use the format name@example.com"
    );
  } else {
    emailInput.setCustomValidity(""); // valid — clear the error
  }
});

⚠️ Always clear the custom message (set it to "") once the input becomes valid — otherwise checkValidity()will keep returning false even for correct input.

4. The validity Property — Pinpoint the Exact Error

Every form element exposes a validity object — a ValidityState — with Boolean flags for each possible failure reason:

Example — different messages for different failures:

const username = document.querySelector("#username");

username.addEventListener("blur", () => {
  if (username.validity.valueMissing) {
    username.setCustomValidity("Username is required.");
  } else if (username.validity.tooShort) {
    username.setCustomValidity(
      `At least ${username.minLength} characters needed — you have ${username.value.length}.`
    );
  } else {
    username.setCustomValidity("");
  }
  username.reportValidity();
});

This is far more helpful than a generic “Please fill in this field.”

5. The willValidate Property

A simple Boolean that tells you whether a given element participates in constraint validation at all. Elements with disabled, hidden, or outside a form will return false.

const input = document.querySelector("input");

if (input.willValidate) {
  console.log("This field will be validated on submit.");
} else {
  console.log("This field is excluded from validation.");
}

Most useful in dynamic forms where you conditionally disable fields.

Live CodePen Demo

The demo below puts all five features together: a registration form with custom error messages, real-time blur validation, and a novalidate-controlled submit flow.

→ Open and fork the demo on CodePen

See the Pen Constraint Validation API by Shakil Alam (@Itxshakil) on CodePen.

Comparison: Default vs. API Validation

Best Practices

Start with HTML attributes. required, type, minlength, pattern — these are free and accessible. The API layers on top.

Add novalidate when going custom. Prevents the browser from showing its own messages before yours.

Always clear setCustomValidity("") on valid input. Failing to do this is the most common bug — the field looks fine but checkValidity() still returns false.

Validate on blur, not just submit. Catching errors field-by-field as the user moves on feels far less frustrating than a wall of errors at the end.

Use aria-live="polite" on error containers. Screen readers will announce the message automatically when it’s injected, no extra code needed.

Write friendly messages. “Your email is missing an ‘@’ — could you add it?” beats “Invalid email” every time.

Conclusion

The HTML Constraint Validation API gives you everything you need to build forms that feel considerate — custom messages, flexible timing, and pinpoint error detection — without a single dependency. Start with the HTML attributes for structure, layer in setCustomValidity() for messaging, and use the validity flags for precision.

The live demo above has all five features working together. Fork it, adapt it to your forms, and your users will thank you.

Further reading:

• Constraint Validation — MDN
• Complex Constraint Examples — MDN
• Client-Side Form Validation — MDN Learn
• Constraint Validation API Browser Support — Can I Use

Please leave this field empty

Oh hi there 👋
It’s nice to meet you.

Sign up to receive awesome content in your inbox.

We don’t spam! Read our privacy policy for more info.

Check your inbox or spam folder to confirm your subscription.