HTMLInputElement.validity — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLInputElement.validity

Beschreibung

Die schreibgeschützte Eigenschaft validity gibt ein ValidityState-Objekt zurück. Es zeigt den aktuellen Validierungszustand eines <input>-Elements. Jede boolesche Eigenschaft steht für eine bestimmte Regel der HTML-Formularvalidierung, zum Beispiel required, pattern, min/max, minlength/maxlength, step oder den Eingabetyp (email, url …).

Das Objekt hat folgende Eigenschaften:

valueMissing: Das Pflichtfeld (required) ist leer.
typeMismatch: Der Wert passt nicht zum Typ, z. B. bei type="email" oder type="url".
patternMismatch: Der Wert entspricht nicht dem Attribut pattern.
tooLong / tooShort: Die Länge verletzt maxlength bzw. minlength.
rangeUnderflow / rangeOverflow: Der Wert liegt unter min bzw. über max.
stepMismatch: Der Wert passt nicht zum Raster von step.
badInput: Der Browser kann die Eingabe nicht umwandeln, z. B. Buchstaben in type="number".
customError: Mit setCustomValidity() wurde eine eigene Fehlermeldung gesetzt.
valid: true, wenn keine der oben genannten Bedingungen zutrifft.

Mit validity kannst du eigene, genaue Fehlermeldungen anzeigen, statt dich auf die Standard-Hinweise des Browsers zu verlassen. Gebräuchlich ist das zusammen mit dem Attribut novalidate am Formular, mit den Events input und invalid sowie mit setCustomValidity(). Das Objekt ist „live“: Es gibt immer den aktuellen Zustand wieder, auch wenn du es zuvor in einer Variable gespeichert hast.

Rückgabewert

Typ

ValidityState

Beschreibung

Ein schreibgeschütztes, live aktualisiertes ValidityState-Objekt mit booleschen Eigenschaften wie valid, valueMissing, typeMismatch, patternMismatch, tooLong, tooShort, rangeUnderflow, rangeOverflow, stepMismatch, badInput und customError.

Beispiele

Validierungszustand eines Pflichtfelds abfragen

const input = document.createElement('input');
input.type = 'email';
input.required = true;

console.log(input.validity.valueMissing); // leer + required
console.log(input.validity.valid);

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

input.value = 'max@example.com';
console.log(input.validity.valid);

true false true true

Eigene Fehlermeldungen je nach Fehlerart

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

const meldung = (v) => {
  if (v.valueMissing) return 'Bitte gib dein Alter ein.';
  if (v.badInput) return 'Bitte nur Zahlen eingeben.';
  if (v.rangeUnderflow) return `Mindestalter ist ${feld.min} Jahre.`;
  if (v.rangeOverflow) return `Höchstens ${feld.max} Jahre erlaubt.`;
  return '';
};

feld.addEventListener('input', () => {
  fehler.textContent = feld.validity.valid ? '' : meldung(feld.validity);
});

Eigene Regel mit setCustomValidity und customError

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

const pruefen = () => {
  pw2.setCustomValidity(pw.value === pw2.value ? '' : 'Passwörter stimmen nicht überein.');
  console.log('customError:', pw2.validity.customError, '| valid:', pw2.validity.valid);
};

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

customError: true | valid: false (bei unterschiedlichen Passwörtern)

Alle gesetzten Fehler-Flags auflisten

const input = document.createElement('input');
input.pattern = '[A-Z]{3}';
input.maxLength = 5;
input.value = 'abc';

const flags = [];
for (const key in input.validity) {
  if (key !== 'valid' && input.validity[key]) flags.push(key);
}
console.log(flags);

["patternMismatch"]

// Wichtig · Fallstricke

Schreibgeschützt: Die Eigenschaften von ValidityState lassen sich nicht direkt setzen. Einen eigenen Fehlerzustand erzeugst du nur mit setCustomValidity('Meldung'). Zum Zurücksetzen rufst du setCustomValidity('') auf, sonst bleibt das Feld dauerhaft ungültig.
tooLong/tooShort: Diese Flags werden meist nur nach echter Nutzereingabe gesetzt. Einen per Skript zugewiesenen value prüfen die Browser dabei in der Regel nicht.
Ausgenommene Felder: Elemente mit disabled oder readonly sowie die Typen hidden, button und reset werden nicht validiert (willValidate === false). validity.valid ist bei ihnen trotzdem true.
badInput: Bei type="number" ist value bei ungültiger Eingabe ein leerer String. Nur validity.badInput zeigt, dass der Nutzer tatsächlich etwas eingetippt hat.
Sicherheit: Die Prüfung im Browser dient nur dem Bedienkomfort. Man kann sie leicht umgehen, deshalb müssen die Daten immer auch auf dem Server geprüft werden.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Dieselbe Eigenschaft gibt es auch bei HTMLSelectElement, HTMLTextAreaElement, HTMLButtonElement, HTMLFieldSetElement, HTMLOutputElement und HTMLObjectElement.

Siehe auch

ValidityState HTMLInputElement.setCustomValidity() HTMLInputElement.checkValidity() HTMLInputElement.reportValidity() HTMLInputElement.validationMessage HTMLInputElement.willValidate