HTMLButtonElement.checkValidity() — Methode · JavaScript-Referenz

Signatur

HTMLButtonElement.prototype.checkValidity()

Beschreibung

Die Methode checkValidity() prüft ein <button>-Element mit der HTML-Einschränkungsvalidierung (engl. Constraint Validation). Ist das Element gültig, gibt sie true zurück. Ist es ungültig, gibt sie false zurück und löst am Element zusätzlich ein abbrechbares invalid-Event aus. Anders als reportValidity() zeigt checkValidity() dem Nutzer keine Fehlermeldung an.

Buttons haben keine Attribute wie required oder pattern. Deshalb kann ein Button in der Praxis nur auf eine Weise ungültig werden: durch eine eigene Fehlermeldung über setCustomValidity(). Das ist nützlich, wenn ein Absende-Button das Absenden blockieren soll, solange eine Bedingung der Anwendung nicht erfüllt ist, zum Beispiel wenn die AGB nicht bestätigt sind oder ein Upload noch läuft.

Nur Buttons mit type="submit" (das ist der Standard) nehmen an der Validierung teil. Buttons mit type="button" oder type="reset", deaktivierte Buttons und Buttons innerhalb eines <datalist> sind davon ausgeschlossen. Bei ihnen ist willValidate false, und checkValidity() gibt immer true zurück.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Button gültig ist oder gar nicht validiert wird. false, wenn eine Einschränkung verletzt ist. In diesem Fall wird zusätzlich ein invalid-Event ausgelöst.

Beispiele

Eigene Fehlermeldung setzen und prüfen

const button = document.createElement('button'); // type="submit" ist Standard
document.body.append(button);

console.log(button.checkValidity()); // gültig

button.setCustomValidity('Bitte zuerst die AGB akzeptieren.');
console.log(button.checkValidity());
console.log(button.validationMessage);

// Mit einem leeren String wird der Button wieder gültig
button.setCustomValidity('');
console.log(button.checkValidity());

true false Bitte zuerst die AGB akzeptieren. true

Absende-Button an eine Checkbox koppeln

// HTML: <form id="f"><input type="checkbox" id="agb"><button id="send">Senden</button></form>
const agb = document.querySelector('#agb');
const send = document.querySelector('#send');

const update = () => {
  send.setCustomValidity(agb.checked ? '' : 'AGB müssen akzeptiert werden.');
};
agb.addEventListener('change', update);
update();

send.addEventListener('invalid', (event) => {
  console.warn('Ungültig:', send.validationMessage);
});

console.log(send.checkValidity()); // löst "invalid" aus

Ungültig: AGB müssen akzeptiert werden. false

Ausgeschlossene Button-Typen

const btn = document.createElement('button');
btn.type = 'button';
btn.setCustomValidity('Wird ignoriert');

console.log(btn.willValidate);
console.log(btn.checkValidity());

btn.type = 'submit';
console.log(btn.willValidate, btn.checkValidity());

btn.disabled = true;
console.log(btn.checkValidity());

false true true false true

// Wichtig · Fallstricke

checkValidity() zeigt dem Nutzer keine Meldung an. Wenn die Browser-Fehlermeldung erscheinen soll, benutzt du reportValidity().
Das invalid-Event steigt nicht im DOM auf (kein Bubbling). Den Listener musst du also direkt am Button registrieren oder am Formular in der Capture-Phase (addEventListener('invalid', fn, true)).
Eine mit setCustomValidity() gesetzte Meldung bleibt bestehen, bis du sie mit einem leeren String '' wieder löschst. Wenn du das vergisst, bleibt das Formular dauerhaft blockiert.
Bei type="button", type="reset" oder disabled gibt die Methode immer true zurück, auch wenn eine eigene Meldung gesetzt ist.
Die Prüfung im Browser ersetzt keine Validierung auf dem Server.
Die Methode wird von allen modernen Browsern unterstützt.

Siehe auch

HTMLButtonElement.reportValidity() HTMLButtonElement.setCustomValidity() HTMLOutputElement.checkValidity() HTMLFormElement.checkValidity() HTMLInputElement.checkValidity()