The Constraint Validation API

Technical Deep Dive & Specifications

2.1 The Complete 10-Flag ValidityState Interface

Under the WHATWG HTML Standard (§ 4.10.21.2), element.validity is a read-only ValidityState interface containing exactly 10 constraint flags and 1 summary flag:

+----------------------------------------------------------------------------------------------------+
|                                THE 10 VALIDITYSTATE FLAGS REFERENCE                                |
+----------------------------------------------------------------------------------------------------+

 FLAG                  TYPE       CORRESPONDING CONSTRAINT RULE
 ───────────────────────────────────────────────────────────────────────────────────────────────────
 1. valueMissing       boolean    Element is 'required' and value is empty.
 2. typeMismatch       boolean    Value violates syntax for type="email" or type="url".
 3. patternMismatch    boolean    Value does not match the 'pattern' regular expression.
 4. tooShort           boolean    Value length is non-zero but strictly less than 'minlength'.
 5. tooLong            boolean    Value length exceeds 'maxlength' (e.g. via DOM assignment).
 6. rangeUnderflow     boolean    Numerical/temporal value is strictly less than 'min'.
 7. rangeOverflow      boolean    Numerical/temporal value is strictly greater than 'max'.
 8. stepMismatch       boolean    Value does not fit the stepping interval '(val - base) % step'.
 9. badInput           boolean    Browser cannot parse input (e.g. typing letters into type="number").
 10. customError       boolean    setCustomValidity() was called with a non-empty error string.
 ───────────────────────────────────────────────────────────────────────────────────────────────────
 *. valid              boolean    SUMMARY: true if and only if ALL 10 flags above are FALSE.

2.2 Methods of the Constraint Validation API

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

// 1. Silent check (Great for enabling/disabling submit buttons or tabs)
if (form.checkValidity()) {
  console.log('All inputs in form are completely valid!');
}

// 2. Interactive check (Triggers native browser error bubble on first failing element)
if (!form.reportValidity()) {
  console.log('Submission blocked; browser focused first invalid control.');
}

2.3 The Universal Error Message Resolver Pattern

Instead of relying on browser default strings, senior engineers map ValidityState flags to application-specific dictionaries:

function resolveErrorMessage(input) {
  const v = input.validity;
  if (v.valid) return '';

  if (v.valueMissing) return `${input.name} is mandatory. Please provide a value.`;
  if (v.typeMismatch) return `Please enter a valid ${input.type} format.`;
  if (v.patternMismatch) return input.title || `Format does not match required pattern.`;
  if (v.tooShort) return `Must be at least ${input.minLength} characters (currently ${input.value.length}).`;
  if (v.tooLong) return `Cannot exceed ${input.maxLength} characters.`;
  if (v.rangeUnderflow) return `Value must be at least ${input.min}.`;
  if (v.rangeOverflow) return `Value cannot exceed ${input.max}.`;
  if (v.stepMismatch) return `Please select a valid interval step (${input.step}).`;
  if (v.badInput) return `Please enter a valid number or date.`;
  if (v.customError) return input.validationMessage;

  return 'Invalid input value.';
}

💻 Interactive Code Playground

Starter Code

The following enterprise diagnostic console allows you to interact with multiple controls and inspect all 10 ValidityState flags in a real-time matrix.

Line-by-Line Code Breakdown

• Lines 131-135 (FLAGS array): Declares all 10 standard WHATWG ValidityState flags in the exact specification taxonomy.
• Lines 137-160 (renderMatrix()): Queries input.validity[flag] dynamically to illuminate the real-time LED diagnostic board.
• Lines 163-176 (resolveErrorMessage()): The enterprise error resolver function that translates raw boolean flags into user-friendly localized copy.
• Lines 183-191 (form.checkValidity() vs form.reportValidity()): Demonstrates the difference between silent evaluation and interactive popup reporting.

Expected Browser Render Output

+------------------------------------+  +------------------------------------+
| Form Inspector                     |  | 10-Point ValidityState Matrix      |
| Select an input to stream flags... |  | Inspecting: [Email] (Value: "")    |
|                                    |  |                                    |
| 1. Email (required, type=email)    |  | [🔴 TRUE ] valueMissing            |
| [                                ] |  | [🟢 FALSE] typeMismatch            |
|                                    |  | [🟢 FALSE] patternMismatch         |
| 2. Code (pattern: [A-Z]{3}-\d{3})  |  | [🟢 FALSE] tooShort                |
| [                                ] |  | [🟢 FALSE] tooLong                 |
|                                    |  | [🟢 FALSE] rangeUnderflow          |
| [ form.reportValidity() ]          |  | [🟢 FALSE] rangeOverflow           |
| [ form.checkValidity()  ]          |  | [⛔ FALSE] SUMMARY: validity.valid |
+------------------------------------+  +------------------------------------+