reportValidity and setCustomValidity

The Constraint Validation API exposes two methods that drive the browser's built-in validation UI: reportValidity (show the tooltip) and setCustomValidity (provide a custom error message). Together they let you customize messages while keeping the native presentation.

checkValidity() silently returns true/false — no UI side effects. reportValidity() does the same check but additionally focuses the first invalid field and shows the browser's validation tooltip. Choose reportValidity when you want native UX for free.

For multi-step wizards, validate each step's fields before advancing: if (step.reportValidity()) { next(); }. The browser handles the error display and the user is focused on the field that needs attention — saving you from reimplementing focus management.

Default messages ("Please fill out this field") may not match your tone. input.setCustomValidity("Username is required") replaces the default with your text. The input is treated as invalid until you clear the message.

input.setCustomValidity("") removes the custom message and re-enables normal validation. Call this whenever you re-validate, otherwise stale custom messages remain even after the user fixes the issue.

For server-side checks (username uniqueness, coupon validity), use setCustomValidity after the async response: const ok = await checkUsername(value); input.setCustomValidity(ok ? "" : "Already taken");. The browser picks up the new validity state immediately.

To use your own error display while still getting the validity tracking, listen to the invalid event and call e.preventDefault() to suppress the native tooltip: input.addEventListener("invalid", (e) => { e.preventDefault(); showError(input, input.validationMessage); }).

setCustomValidity supports only one custom message at a time. To enforce several rules, check each and call setCustomValidity with the most relevant message in priority order. The first failing rule is the one displayed.

If you set a custom message for an empty required field, both your message and the default may conflict. Pick one approach per field: either disable the built-in constraint (use type="text" instead of type="email" and validate via setCustomValidity), or trust the built-in entirely.

For cross-field validation (password confirmation matching), apply setCustomValidity to the related field: confirmInput.setCustomValidity(confirmInput.value === passInput.value ? "" : "Passwords do not match"). The form is invalid until both match.

Built-in messages are localized by the browser based on user language. Custom messages set via setCustomValidity must be in the right language yourself — read navigator.language or your own i18n state and supply the matching translation.

Open DevTools and try every invalid path: empty submit, partial input, format mismatch, async failure. Verify that the correct message shows, that fixing the issue clears it, and that submitting a valid form proceeds. Edge cases (paste of invalid format, browser autofill) deserve specific tests.

After calling input.setCustomValidity("Already taken"), how do you tell the browser the input is valid again?

reportValidity triggers the browser's built-in validation UI (focus + tooltip), perfect for programmatic checks. setCustomValidity overrides default messages with your text — clear with empty string when valid again. Listen to the invalid event with preventDefault for entirely custom error displays. Use for cross-field validation, async checks, and localized custom messages.