CKTIS / JavaScript
HTMLInputElement.setCustomValidity — a custom validation error
HTMLInputElement.setCustomValidity sets or clears a form field's custom error. An empty string clears that error without disabling other constraints.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
input.setCustomValidity(message)HTMLInputElement.setCustomValidity is a browser form-validation API method defined by the HTML Living Standard, not ECMAScript. It is supported in current browser engines; the presence of Node 24 does not establish availability of this API.
Calling input.setCustomValidity(message) with a nonempty string sets input.validity.customError to true. Passing "" clears only the custom error: constraints such as required still apply. The method returns undefined, not a validation result.
The method itself does not display a message. checkValidity() checks validity without displaying error UI. If the field fails validation, reportValidity() returns false, and the browser reports the problem to the user only if the invalid event is not canceled. Canceling the event does not change the return value. Elements barred from validation can retain a custom error even though they do not block a validated form submission.
After a value changes, recompute the rule and explicitly clear any stale error, typically in an input event handler. In the example, the final false false means there is no custom error, but required remains unsatisfied. Client-side validation does not replace server-side validation.
Examples
const input = document.createElement("input");
input.required = true;
input.value = "admin";
function validate() {
input.setCustomValidity(
input.value === "admin" ? "Reserved name." : ""
);
}
validate();
console.log(input.validity.customError, input.checkValidity());
input.value = "alex";
validate();
console.log(input.validity.customError, input.checkValidity());
input.value = "";
validate();
console.log(input.validity.customError, input.checkValidity());Result
true false false true false false
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.