Using setCustomValidity() on an HTML form control, how do you make the browser show your own error text — for example "passwords do not match" — and what breaks if you get one step wrong?

## What the method is for The declarative constraints — `required`, `pattern`, `min`, `max`, `minlength` — only describe one field in isolation. Plenty of real rules are not like that: - "Password confirmation must equal the password" (depends on another field). - "End date must be after start date" (depends on another field). - "That username is already taken" (depends on a server). - "This coupon has expired" (depends on business state). `setCustomValidity(message)` is the escape hatch that lets any of those participate in the same machinery the built-in constraints use. ## What it changes Calling it with a non-empty string: - sets `element.validity.customError` to `true` and `element.validity.valid` to `false`; - makes `element.validationMessage` return your string; - makes the element match `:invalid`; - makes `checkValidity()` return `false` and blocks native form submission; - makes the browser display **your** text in the place its own message would have appeared. Calling it with the empty string clears the custom error. Note carefully what that does *not* do: it does not make the element valid. Clearing `customError` simply removes your addition; the element is still subject to `required`, `pattern` and the rest. ## The sticky-flag trap This is the entire reason the question gets asked. Built-in constraints are recomputed automatically whenever the value changes. A custom error is not — it stays exactly as you last set it until you set it again. The classic broken code: ```js confirm.addEventListener('input', () => { if (confirm.value !== password.value) { confirm.setCustomValidity('Passwords do not match'); } // no else — the error never goes away }); ``` The user mistypes once, fixes it, and the form is now unsubmittable with a message about a mismatch that no longer exists. The fix is to make every run of the handler set the state unconditionally: ```js function syncConfirm() { confirm.setCustomValidity( confirm.value === password.value ? '' : 'Passwords do not match' ); } confirm.addEventListener('input', syncConfirm); password.addEventListener('input', syncConfirm); ``` Note the second listener. The confirmation field's validity depends on a *different* field, so editing the password must re-evaluate the confirmation too — otherwise the user fixes the mismatch from the other side and the stale error survives. ## When the message is actually shown Setting a custom error does not display anything by itself. The string surfaces when something reports: an attempted submission, or an explicit `reportValidity()` call. Between those moments the control is silently invalid — it matches `:invalid`, and `checkValidity()` says `false`, but the user sees nothing. If you want feedback the moment the fields diverge, you render it yourself and use the custom validity purely as the gate that stops submission. ## Asynchronous rules Server-dependent messages fit the same shape, with one caveat: the answer arrives late. ```js async function checkUsername() { username.setCustomValidity('Checking…'); // invalid while we wait const taken = await isTaken(username.value); username.setCustomValidity(taken ? 'That username is taken' : ''); } ``` Marking the field invalid while the request is in flight prevents a submission from racing past an unchecked value, and the final call resolves it either way. Stale responses need the usual guard — ignore a reply whose value no longer matches the current one. And a server-side rule checked here still has to be enforced on the server: this is UI, not the decision. ## Localization and the alternative Because you supply the string, custom validity messages are in **your** language rather than the browser's — one of the few ways to get consistent wording out of the native bubbles. But the bubble itself is still the browser's: unstyled, transient, one at a time, and not in the DOM. Many design systems therefore use `setCustomValidity()` only as the invalidity *signal* — so the form cannot submit and `:invalid` matches — while rendering the visible text themselves in ordinary markup next to the field. ## Weak answers "Set the message once and the browser clears it when the user fixes the value" — it does not; you clear it. "`setCustomValidity('')` makes the field valid" — it only removes your error; `required` may still be failing. "You can pass HTML for a styled message" — the argument is plain text; nothing renders markup.