ValidityState — Schnittstelle · JavaScript-Referenz

Signatur

interface ValidityState

Beschreibung

Ein ValidityState-Objekt erhält man über die Eigenschaft validity eines Formularelements (HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement, HTMLButtonElement, HTMLOutputElement, HTMLFieldSetElement, HTMLObjectElement) oder über ElementInternals.validity bei formularfähigen Custom Elements. Es lässt sich nicht selbst instanziieren und ist live: Die Werte spiegeln stets den aktuellen Zustand des Elements wider.

Das Objekt enthält ausschließlich schreibgeschützte boolesche Eigenschaften, von denen jede einen bestimmten Validierungsfehler anzeigt:

valueMissing – ein required-Feld ist leer.
typeMismatch – der Wert passt nicht zum type (z. B. email, url).
patternMismatch – der Wert entspricht nicht dem Attribut pattern.
tooLong / tooShort – Länge verletzt maxlength bzw. minlength.
rangeUnderflow / rangeOverflow – Wert kleiner als min bzw. größer als max.
stepMismatch – Wert passt nicht zum Raster von step.
badInput – der Browser kann die Eingabe nicht umwandeln (z. B. Buchstaben in type="number").
customError – per setCustomValidity() wurde eine eigene Fehlermeldung gesetzt.
valid – true, wenn keine der obigen Eigenschaften true ist.

Man nutzt ValidityState, um eigene, präzise Fehlermeldungen anzuzeigen, statt sich auf die generischen Browser-Meldungen zu verlassen – typischerweise kombiniert mit novalidate am Formular, den Events input/invalid und checkValidity()/reportValidity().

Rückgabewert

Typ

ValidityState

Beschreibung

Wird über element.validity bzw. ElementInternals.validity geliefert; alle Eigenschaften sind schreibgeschützte boolean-Werte.

Beispiele

Zugriff auf ValidityState und Fehlerursache ermitteln

// <input id="email" type="email" required>
const input = document.querySelector('#email');
input.value = 'kein-at-zeichen';

const { validity } = input;
console.log(validity instanceof ValidityState);
console.log(validity.valid);
console.log(validity.typeMismatch);
console.log(validity.valueMissing);

true false true false

Eigene Fehlermeldungen je nach Fehlerart

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

const meldung = (v) => {
  if (v.valueMissing) return 'Bitte geben Sie Ihr Alter ein.';
  if (v.badInput) return 'Bitte nur Zahlen eingeben.';
  if (v.rangeUnderflow) return 'Sie müssen mindestens 18 Jahre alt sein.';
  if (v.rangeOverflow) return 'Bitte ein realistisches Alter angeben.';
  return '';
};

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

customError mit setCustomValidity()

// <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.value = 'geheim';
pw2.value = 'geheim1';
pruefen();
pw2.value = 'geheim';
pruefen();

customError: true | valid: false customError: false | valid: true

Alle Fehler eines Formulars sammeln

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

const fehlerarten = ['valueMissing', 'typeMismatch', 'patternMismatch', 'tooLong', 'tooShort',
  'rangeUnderflow', 'rangeOverflow', 'stepMismatch', 'badInput', 'customError'];

form.addEventListener('submit', (event) => {
  const ungueltig = [...form.elements]
    .filter((el) => el.willValidate && !el.validity.valid)
    .map((el) => ({ name: el.name, fehler: fehlerarten.filter((k) => el.validity[k]) }));

  if (ungueltig.length) {
    event.preventDefault();
    console.table(ungueltig);
  }
});

// Wichtig · Fallstricke

Nicht konstruierbar: new ValidityState() wirft einen TypeError; das Objekt kommt immer über validity.
Nur lesend: Eigenschaften lassen sich nicht setzen. Eigene Fehler nur über setCustomValidity(msg) – und danach unbedingt mit setCustomValidity('') zurücksetzen, sonst bleibt das Feld dauerhaft ungültig.
Programmatische Werte: tooLong/tooShort werden in der Regel nur bei Nutzereingaben gesetzt, nicht wenn value per Skript zugewiesen wird.
badInput: Bei ungültiger Eingabe in type="number" liefert value einen leeren String – nur badInput verrät den eigentlichen Fehler.
Ausgeschlossene Elemente: Deaktivierte oder readonly-Felder sowie type="hidden" werden nicht validiert (willValidate === false); validity.valid ist dann true.
Sicherheit: Clientseitige Validierung ist reine Benutzerführung und muss serverseitig wiederholt werden.
Kompatibilität: In allen modernen Browsern verfügbar; ElementInternals.validity für Custom Elements erst in neueren Versionen (Safari ab 16.4).

Siehe auch

XRLightEstimate AudioData PaintSize VideoFrame XRRenderState