HTMLInputElement.checkValidity() — Methode · JavaScript-Referenz

Signatur

HTMLInputElement.prototype.checkValidity()

Beschreibung

checkValidity() gehört zur Constraint Validation API. Die Methode prüft den aktuellen Wert eines Eingabefelds gegen alle Regeln, die für das Feld gelten: HTML-Attribute wie required, pattern, min/max, minlength/maxlength, step und die Typprüfung von type="email" oder type="url". Dazu kommen eigene Fehler, die Sie mit setCustomValidity() gesetzt haben.

Ist das Feld gültig, gibt die Methode true zurück. Ist es ungültig, gibt sie false zurück und löst am Element ein abbrechbares invalid-Event aus. Anders als reportValidity() zeigt checkValidity() keine Fehlermeldung (Tooltip) im Browser an. Damit eignet sich die Methode gut für eigene Validierungsoberflächen, zum Beispiel um einen Absenden-Button zu aktivieren oder zu deaktivieren oder um eigene Fehlertexte einzublenden.

Welche Regel genau verletzt ist, verrät das Objekt element.validity (ValidityState) mit Eigenschaften wie valueMissing, typeMismatch oder patternMismatch. Die passende Meldung des Browsers steht in element.validationMessage. Mit HTMLFormElement.checkValidity() prüfen Sie ein ganzes Formular auf einmal.

Beispiele

Einfache Prüfung eines Pflichtfelds

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

email.value = '';
console.log(email.checkValidity());          // leer, aber required
console.log(email.validity.valueMissing);

email.value = 'keine-mail';
console.log(email.checkValidity());
console.log(email.validity.typeMismatch);

email.value = 'max@example.com';
console.log(email.checkValidity());

false true false true true

Absenden-Button nur bei gültiger Eingabe aktivieren

// HTML:
// <input id="plz" pattern="\d{5}" required>
// <button id="senden" disabled>Senden</button>
const plz = document.querySelector('#plz');
const button = document.querySelector('#senden');

plz.addEventListener('input', () => {
  // Keine Browser-Meldung, nur Zustand prüfen
  button.disabled = !plz.checkValidity();
});

Eigene Fehlermeldungen über das invalid-Event

// HTML: <input id="alter" type="number" min="18" max="120" required>
//       <span id="fehler"></span>
const alter = document.querySelector('#alter');
const fehler = document.querySelector('#fehler');

alter.addEventListener('invalid', (event) => {
  event.preventDefault(); // Standard-Verhalten des Browsers unterdrücken
  if (alter.validity.valueMissing) {
    fehler.textContent = 'Bitte geben Sie Ihr Alter an.';
  } else if (alter.validity.rangeUnderflow) {
    fehler.textContent = 'Sie müssen mindestens 18 Jahre alt sein.';
  } else {
    fehler.textContent = alter.validationMessage;
  }
});

alter.value = '16';
const ok = alter.checkValidity(); // löst invalid aus
console.log(ok, fehler.textContent);

false Sie müssen mindestens 18 Jahre alt sein.

Eigene Regel mit setCustomValidity()

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

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

pw.value = 'geheim123';
pw2.value = 'geheim124';
vergleiche();
console.log(pw2.checkValidity(), pw2.validity.customError);

false true

// Wichtig · Fallstricke

Keine sichtbare Rückmeldung: checkValidity() zeigt dem Nutzer nichts an. Wenn der Browser die Fehlermeldung zeigen soll, verwenden Sie reportValidity().
Von der Validierung ausgenommene Felder gelten immer als gültig und geben true zurück. Das betrifft Felder mit disabled oder readonly sowie type="hidden", "button", "reset" und Felder in einem deaktivierten <fieldset>. willValidate zeigt an, ob ein Feld überhaupt geprüft wird.
Eigene Fehler bleiben bestehen: Ein mit setCustomValidity('…') gesetzter Fehler bleibt aktiv, bis Sie ihn mit setCustomValidity('') wieder löschen. Sonst bleibt das Feld für immer ungültig.
Das novalidate-Attribut am Formular verhindert nur die automatische Prüfung beim Absenden. checkValidity() prüft trotzdem.
Das invalid-Event steigt nicht im DOM auf (kein Bubbling). Wenn Sie es am Formular abfangen wollen, registrieren Sie den Listener mit { capture: true }.
Sicherheit: Die Prüfung im Browser dient nur dem Komfort und lässt sich leicht umgehen. Eingaben müssen Sie immer zusätzlich auf dem Server prüfen.
Kompatibilität: Die Methode funktioniert in allen modernen Browsern, auch schon im Internet Explorer 10 und neuer.

Siehe auch

HTMLInputElement.reportValidity() HTMLInputElement.setCustomValidity() HTMLInputElement.select() HTMLInputElement.showPicker() HTMLInputElement.stepDown()