HTMLInputElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLInputElement.prototype.setCustomValidity(message)

Beschreibung

Mit setCustomValidity() bindest du eigene Prüfregeln in die eingebaute Formularvalidierung des Browsers ein (Constraint Validation API). Übergibst du einen nicht leeren String, gilt das Feld als ungültig: validity.customError wird true, validity.valid wird false und die Pseudoklasse :invalid greift. Beim Absenden blockiert der Browser das Formular und zeigt deine Meldung als Tooltip an.

Einsatzgebiete sind Prüfungen, die sich mit HTML-Attributen wie required, pattern oder min/max nicht ausdrücken lassen, zum Beispiel „Passwort und Wiederholung müssen übereinstimmen“, serverseitige Prüfungen (ob ein Benutzername schon vergeben ist) oder verständlichere, lokalisierte Texte statt der Standardmeldungen des Browsers.

Wichtig: Die Meldung bleibt so lange bestehen, bis du explizit setCustomValidity('') aufrufst. Deshalb setzt man die Prüfung typischerweise in einem input- oder change-Handler zurück und prüft dann neu. Die Methode zeigt die Meldung nicht selbst an; dafür sorgen reportValidity() oder der Absendeversuch.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Fehlermeldung. Ein nicht leerer String macht das Feld ungültig, ein leerer String (`''`) löscht den benutzerdefinierten Fehler. Andere Werte werden in einen String umgewandelt (`undefined` wird zu `'undefined'`).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Passwort-Bestätigung prüfen

// HTML: <input id="pw" type="password" required>
//       <input id="pw2" type="password" required>
const pw = document.querySelector('#pw');
const pw2 = document.querySelector('#pw2');

const checkMatch = () => {
  pw2.setCustomValidity(
    pw.value === pw2.value ? '' : 'Die Passwörter stimmen nicht überein.'
  );
};

pw.addEventListener('input', checkMatch);
pw2.addEventListener('input', checkMatch);

Standardmeldung durch eigenen Text ersetzen

// HTML: <input id="email" type="email" required>
const email = document.querySelector('#email');

email.addEventListener('input', () => {
  email.setCustomValidity(''); // zuerst zurücksetzen, sonst bleibt das Feld ungültig
  if (email.validity.valueMissing) {
    email.setCustomValidity('Bitte gib deine E-Mail-Adresse ein.');
  } else if (email.validity.typeMismatch) {
    email.setCustomValidity('Das sieht nicht nach einer gültigen E-Mail-Adresse aus.');
  }
});

email.addEventListener('invalid', () => {
  if (email.validity.valueMissing) {
    email.setCustomValidity('Bitte gib deine E-Mail-Adresse ein.');
  }
});

Asynchrone Serverprüfung mit reportValidity()

// HTML: <input id="user" name="user" required>
const user = document.querySelector('#user');

user.addEventListener('change', async () => {
  user.setCustomValidity('');
  const res = await fetch(`/api/username-frei?name=${encodeURIComponent(user.value)}`);
  const { frei } = await res.json();
  if (!frei) {
    user.setCustomValidity(`Der Name „${user.value}“ ist bereits vergeben.`);
  }
  user.reportValidity(); // Meldung sofort anzeigen
  console.log(user.validity.customError, user.validationMessage);
});

true Der Name „max“ ist bereits vergeben.

// Wichtig · Fallstricke

Häufigster Fehler: vergessen, mit setCustomValidity('') zurückzusetzen. Dann bleibt das Feld dauerhaft ungültig und das Formular lässt sich nicht mehr absenden, auch wenn der Nutzer den Wert korrigiert.
Die Methode zeigt nichts an. Sichtbar wird die Meldung erst beim Absenden oder durch reportValidity(); checkValidity() löst nur das invalid-Event aus.
Bei novalidate am Formular oder formnovalidate am Button wird der Fehler beim Absenden ignoriert. Deaktivierte (disabled) oder readonly-Felder werden nicht validiert.
Aussehen und Anzeigedauer des Tooltips hängen vom Browser ab und lassen sich nicht gestalten. Für eigene Fehlerdarstellungen liest du validationMessage aus und gibst den Text selbst aus, zum Beispiel über ein Element mit aria-live.
Clientseitige Validierung verbessert nur die Bedienung und ist kein Schutz. Eingaben müssen immer auch auf dem Server geprüft werden.
Die gleiche Methode gibt es auch bei HTMLSelectElement, HTMLTextAreaElement, HTMLButtonElement, HTMLFieldSetElement, HTMLOutputElement und HTMLObjectElement. Für Custom Elements gibt es ElementInternals.setValidity().

Siehe auch

HTMLInputElement.reportValidity() HTMLInputElement.checkValidity() HTMLInputElement.validity HTMLInputElement.validationMessage ValidityState ElementInternals.setValidity()