HTMLFormElement.checkValidity() — Methode · JavaScript-Referenz

Signatur

HTMLFormElement.prototype.checkValidity()

Beschreibung

Die Methode checkValidity() eines <form>-Elements führt die Constraint Validation (Einschränkungsvalidierung) für alle zugehörigen Steuerelemente aus: required, pattern, min/max, minlength/maxlength, type="email"/"url" sowie eigene Fehler, die mit setCustomValidity() gesetzt wurden. Sind alle Felder gültig, liefert sie true, andernfalls false.

Für jedes ungültige Steuerelement wird ein invalid-Event ausgelöst, das nicht nach oben weitergereicht wird (kein Bubbling), aber abbrechbar ist. Anders als bei reportValidity() zeigt der Browser dabei keine Fehlermeldungen oder Tooltips an. Das Formular wird also still geprüft.

Typische Einsatzfälle sind: ein „Absenden“-Button nur aktivieren, wenn das Formular gültig ist; Formulare mit novalidate und eigener Fehleranzeige prüfen; oder vor einem fetch()-Versand per JavaScript sicherstellen, dass die Eingaben den Regeln entsprechen.

Geprüft werden nur Elemente, die für die Validierung in Frage kommen. Deaktivierte Felder (disabled), Felder mit readonly, <fieldset>, <output>, type="hidden" sowie Buttons vom Typ reset und button werden ausgelassen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn alle zu prüfenden Steuerelemente gültig sind, sonst false. Zusätzlich wird an jedem ungültigen Element ein invalid-Event ausgelöst.

Beispiele

Formular vor dem Versand per fetch prüfen

// HTML: <form id="kontakt" novalidate>
//   <input name="email" type="email" required>
//   <button>Senden</button>
// </form>
const form = document.querySelector('#kontakt');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  if (!form.checkValidity()) {
    console.log('Formular ungültig – Versand abgebrochen');
    return;
  }

  const response = await fetch('/api/kontakt', {
    method: 'POST',
    body: new FormData(form)
  });
  console.log('Status:', response.status);
});

Formular ungültig – Versand abgebrochen

Absenden-Button live aktivieren oder deaktivieren

// HTML: <form id="login">
//   <input name="user" required minlength="3">
//   <input name="pass" type="password" required>
//   <button id="submit" disabled>Anmelden</button>
// </form>
const form = document.querySelector('#login');
const button = document.querySelector('#submit');

const updateButton = () => {
  button.disabled = !form.checkValidity();
};

form.addEventListener('input', updateButton);
updateButton();

Eigene Fehleranzeige über das invalid-Event

const form = document.querySelector('form');

// invalid wird nicht weitergereicht (kein Bubbling), daher Capture-Phase nutzen
form.addEventListener('invalid', (event) => {
  const field = event.target;
  field.classList.add('fehler');
  console.log(`${field.name}: ${field.validationMessage}`);
}, true);

const ok = form.checkValidity();
console.log('Gültig?', ok);

email: Füllen Sie dieses Feld aus. Gültig? false

Eigene Regel mit setCustomValidity einbinden

const form = document.querySelector('#registrierung');
const pw = form.elements.passwort;
const pw2 = form.elements.passwort2;

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

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

pw.value = 'geheim1';
pw2.value = 'geheim2';
pruefeGleichheit();
console.log(form.checkValidity());

false

// Wichtig · Fallstricke

Keine sichtbare Rückmeldung: checkValidity() zeigt keine Browser-Fehlermeldungen an. Wenn die Meldungen erscheinen sollen, reportValidity() verwenden.
novalidate wird ignoriert: Das Attribut unterdrückt nur die automatische Prüfung beim Absenden. checkValidity() prüft trotzdem.
invalid-Event bubbelt nicht: Wer den Listener am Formular registriert, muss die Capture-Phase nutzen (addEventListener('invalid', fn, true)). Wird das Event mit preventDefault() abgebrochen, ändert das nichts am Rückgabewert.
Eigene Fehler zurücksetzen: Ein mit setCustomValidity('…') gesetzter Fehler bleibt bestehen, bis er mit setCustomValidity('') gelöscht wird. Sonst liefert die Methode dauerhaft false.
Werte aus JavaScript: Wird value per Skript gesetzt, greifen minlength/maxlength in manchen Browsern erst nach einer Eingabe durch den Nutzer (Stichwort „dirty flag“). required und pattern greifen dagegen sofort.
Sicherheit: Die Prüfung im Browser lässt sich leicht umgehen und ersetzt keine Validierung auf dem Server.
Die Methode wird von allen modernen Browsern unterstützt. Sie gibt es auch auf einzelnen Steuerelementen, etwa HTMLInputElement.checkValidity().

Siehe auch

HTMLFormElement.reportValidity() HTMLInputElement.checkValidity() HTMLInputElement.setCustomValidity() ValidityState HTMLFormElement.requestSubmit()