WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

HTMLInputElement.setCustomValidity — ein eigener Validierungsfehler

HTMLInputElement.setCustomValidity setzt oder löscht einen eigenen Fehler eines Formularfelds. Eine leere Zeichenfolge löscht diesen Fehler, hebt aber andere Einschränkungen nicht auf.

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 ist eine Methode der browserseitigen Formularvalidierungs-API, die im HTML Living Standard und nicht in ECMAScript definiert ist. Sie wird von aktuellen Browser-Engines unterstützt; die Verfügbarkeit von Node 24 belegt nicht, dass diese API verfügbar ist.

Ein Aufruf von input.setCustomValidity(message) mit einer nicht leeren Zeichenfolge setzt input.validity.customError auf true. Die Übergabe von "" löscht nur den eigenen Fehler: Einschränkungen wie required gelten weiterhin. Die Methode gibt undefined zurück, kein Validierungsergebnis.

Die Methode selbst zeigt keine Meldung an. checkValidity() prüft die Gültigkeit, ohne einen Fehler anzuzeigen. Besteht das Feld die Validierung nicht, gibt reportValidity() false zurück. Der Browser meldet das Problem nur dann, wenn das Ereignis invalid nicht abgebrochen wird. Das Abbrechen des Ereignisses ändert den Rückgabewert nicht. Elemente, die von der Validierung ausgeschlossen sind, können einen eigenen Fehler behalten, obwohl sie das validierte Absenden eines Formulars nicht verhindern.

Nach einer Wertänderung muss die Regel erneut ausgewertet und ein veralteter Fehler ausdrücklich gelöscht werden, üblicherweise in einem input-Ereignishandler. Im Beispiel bedeutet das abschließende false false, dass kein eigener Fehler vorliegt, aber required nicht erfüllt ist. Die clientseitige Validierung ersetzt keine serverseitige Validierung.

Beispiele

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());

Ergebnis

true false
false true
false false

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen