Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

The constraint validation API

Reference for the constraint validation API: checkValidity(), reportValidity(), setCustomValidity(), the validity flags and validationMessage for custom form checks.

HTML attributes such as required, type="email", min, max, minlength, maxlength and pattern give form controls built-in rules. The constraint validation API is the JavaScript side: it lets you ask whether a control or a whole form is valid, find out exactly why not, show the browser's error bubbles on demand and add your own rules with custom messages.

JavaScript
if (!form.checkValidity()) {
  console.log("The form has invalid fields");
}
input.setCustomValidity("Please pick a unique name");

Try it

Inspect the validity flags
A custom rule with setCustomValidity()

Syntax

JavaScript
control.checkValidity()
control.reportValidity()
control.setCustomValidity(message)
control.validity            // ValidityState
control.validationMessage   // string
control.willValidate        // boolean
form.checkValidity()
form.reportValidity()

Methods and properties

Name Description
checkValidity() Returns true if the control (or all controls of the form) satisfies its constraints. For invalid ones, fires a cancelable invalid event at each.
reportValidity() Like checkValidity(), but also shows the browser's error message and focuses the first invalid control.
setCustomValidity(message) A non-empty string marks the control invalid with that message; an empty string clears the custom error.
validity A ValidityState with boolean flags (see below).
validationMessage The message the browser would show, or an empty string.
willValidate false for disabled, read-only (for some types), hidden and button controls, which are exempt.

ValidityState flags

Flag True when
valueMissing A required control is empty.
typeMismatch The value does not fit type="email" or type="url".
patternMismatch The value does not match pattern.
tooShort / tooLong Shorter than minlength or longer than maxlength (only after user edits).
rangeUnderflow / rangeOverflow Below min or above max.
stepMismatch The value does not fit the step.
badInput The browser cannot convert what the user typed (letters in a number field).
customError setCustomValidity() was called with a message.
valid None of the above is true.

Return value

The check and report methods return a boolean; setCustomValidity() returns undefined.

Usage notes

  • Custom errors stay until cleared. Forgetting setCustomValidity("") is the classic bug: the field stays invalid forever. Reset it at the start of every check.
  • novalidate only stops the automatic UI. With novalidate on the form (or formnovalidate on a button) the browser submits without checking, but checkValidity() and the CSS pseudo-classes still work, so you can show your own messages.
  • Submit is blocked automatically when any control is invalid; the submit event does not fire. To validate on your own timing, call reportValidity() from a click handler.
  • invalid does not bubble. Listen on the control itself, or use the capture phase on the form.
  • CSS hooks: :valid, :invalid, :user-valid and :user-invalid. The user- variants only match after the user interacts, which avoids showing errors on a fresh form.
  • Accessibility. Native bubbles are announced by many screen readers, but if you build your own messages, connect them with aria-describedby and set aria-invalid.
  • Never rely on it for security. Client-side checks help users; the server must validate again.
  • Messages are localized by the browser, and their wording differs between browsers.

Browser support

The core API is supported in all current browsers. :user-valid and :user-invalid are newer, so check a compatibility table.