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.
if (!form.checkValidity()) { console.log("The form has invalid fields"); } input.setCustomValidity("Please pick a unique name");
Try it
Syntax
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. novalidateonly stops the automatic UI. Withnovalidateon the form (orformnovalidateon a button) the browser submits without checking, butcheckValidity()and the CSS pseudo-classes still work, so you can show your own messages.- Submit is blocked automatically when any control is invalid; the
submitevent does not fire. To validate on your own timing, callreportValidity()from a click handler. invaliddoes not bubble. Listen on the control itself, or use the capture phase on the form.- CSS hooks:
:valid,:invalid,:user-validand:user-invalid. Theuser-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-describedbyand setaria-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.