Signatur
Beschreibung
Die Eigenschaft customError des ValidityState-Objekts (erreichbar über element.validity) zeigt an, ob ein Formularelement durch eine benutzerdefinierte Validierungsmeldung als ungültig markiert wurde. Sie ist genau dann true, wenn zuletzt setCustomValidity() mit einem nicht-leeren String aufgerufen wurde.
Damit lassen sich Prüfregeln umsetzen, die über die eingebauten HTML-Attribute (required, pattern, min/max usw.) hinausgehen – etwa „Passwort-Wiederholung muss übereinstimmen“ oder Ergebnisse einer Serverprüfung. Solange customError true ist, ist auch validity.valid false, das Element passt auf die CSS-Pseudoklasse :invalid und das Formular wird beim Absenden blockiert.
Wichtig: Der Zustand bleibt bestehen, bis setCustomValidity("") aufgerufen wird. Man muss den Fehler also aktiv zurücksetzen, typischerweise im input-Event, bevor man die eigene Regel erneut prüft.
Beispiele
Grundlegende Abfrage nach setCustomValidity()
const input = document.createElement('input');
console.log(input.validity.customError); // Ausgangszustand
input.setCustomValidity('Dieser Benutzername ist bereits vergeben.');
console.log(input.validity.customError, input.validity.valid);
input.setCustomValidity(''); // Fehler zurücksetzen
console.log(input.validity.customError, input.validity.valid);Passwort-Wiederholung prüfen
// <input id="pw" type="password" required>
// <input id="pw2" type="password" required>
const pw = document.querySelector('#pw');
const pw2 = document.querySelector('#pw2');
const checkMatch = () => {
// Erst zurücksetzen, dann neu bewerten
pw2.setCustomValidity('');
if (pw2.value && pw.value !== pw2.value) {
pw2.setCustomValidity('Die Passwörter stimmen nicht überein.');
}
console.log('customError:', pw2.validity.customError);
};
pw.addEventListener('input', checkMatch);
pw2.addEventListener('input', checkMatch);Asynchrone Serverprüfung und Fehlerursache unterscheiden
// <form id="reg"><input name="user" required><button>Senden</button></form>
const form = document.querySelector('#reg');
const user = form.elements.user;
user.addEventListener('input', () => user.setCustomValidity(''));
user.addEventListener('change', async () => {
const res = await fetch(`/api/user-exists?name=${encodeURIComponent(user.value)}`);
const { exists } = await res.json();
user.setCustomValidity(exists ? 'Name bereits vergeben.' : '');
});
form.addEventListener('submit', (event) => {
if (!user.checkValidity()) {
event.preventDefault();
const { validity } = user;
if (validity.valueMissing) console.log('Feld ist leer');
else if (validity.customError) console.log('Eigener Fehler:', user.validationMessage);
user.reportValidity();
}
});// Wichtig · Fallstricke
- Kein automatisches Zurücksetzen: Ein einmal gesetzter Fehler bleibt aktiv, auch wenn der Nutzer den Wert korrigiert. Ohne
setCustomValidity('')lässt sich das Formular nie absenden – der häufigste Fehler in der Praxis. - Die Eigenschaft ist schreibgeschützt; eine Zuweisung wie
validity.customError = falsewird ignoriert (im Strict Mode kein Fehler, da nur Getter – Wert ändert sich trotzdem nicht). Steuerung ausschließlich übersetCustomValidity(). - Andere Validierungsfehler (
valueMissing,patternMismatch…) können gleichzeitigtruesein;customErrorsagt nur etwas über die eigene Meldung aus. - Elemente mit
novalidateam Formular oder deaktivierte Elemente (disabled) nehmen nicht an der Validierung teil –customErrorkann dennochtruesein, blockiert dann aber nicht. - Bei Form-assoziierten Custom Elements setzt man den Zustand über
ElementInternals.setValidity({ customError: true }, msg). - Kompatibilität: in allen modernen Browsern seit Jahren unterstützt.