HTMLButtonElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLButtonElement.prototype.setCustomValidity(message)

Beschreibung

Mit setCustomValidity() hängen Sie eigene Prüfregeln an die eingebaute Formularvalidierung des Browsers (Constraint Validation API). Übergeben Sie einen nicht leeren Text, bekommt der Button einen benutzerdefinierten Fehler: validity.customError wird true, validity.valid wird false und validationMessage enthält Ihren Text. Mit einem leeren String "" heben Sie den Fehler wieder auf.

Bei <button>-Elementen gilt das nur für Absende-Buttons (type="submit", das ist der Standard). Ein ungültiger Absende-Button blockiert das Absenden des Formulars. Er passt dann auf die CSS-Pseudoklasse :invalid, und das zugehörige Formular passt auf form:invalid. Buttons mit type="button" oder type="reset" sind von der Validierung ausgeschlossen (willValidate === false). Bei ihnen wird die Meldung zwar gespeichert, hat aber keine Wirkung.

Typische Einsätze: das Absenden erst erlauben, wenn eine Bedingung erfüllt ist, die sich nicht an einem einzelnen Eingabefeld festmachen lässt. Beispiele sind „AGB akzeptiert“, „mindestens ein Artikel im Warenkorb“ oder „Upload noch nicht fertig“. Mit reportValidity() zeigt der Browser die Meldung als Sprechblase direkt am Button an.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Fehlermeldung. Ein nicht leerer String markiert das Element als ungültig. `""` hebt den benutzerdefinierten Fehler auf. Andere Werte werden in einen String umgewandelt, `null` wird also zu `"null"`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Wirkung sieht man an validity, validationMessage und checkValidity().

Beispiele

Fehler setzen und wieder aufheben

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

btn.setCustomValidity('Bitte zuerst die AGB akzeptieren.');
console.log(btn.validity.customError, btn.checkValidity());
console.log(btn.validationMessage);

btn.setCustomValidity(''); // Fehler aufheben
console.log(btn.validity.valid);

true false Bitte zuerst die AGB akzeptieren. true

Absenden erst nach AGB-Zustimmung erlauben

// HTML: <form id="order"><label><input type="checkbox" id="agb"> AGB akzeptieren</label>
//       <button id="send">Bestellen</button></form>
const agb = document.querySelector('#agb');
const send = document.querySelector('#send');

const update = () => {
  send.setCustomValidity(agb.checked ? '' : 'Bitte akzeptieren Sie die AGB.');
};

agb.addEventListener('change', update);
update(); // Anfangszustand setzen

// Beim Klick verhindert der Browser das Absenden und zeigt die Meldung am Button an.

Warten auf einen laufenden Upload und Meldung anzeigen

const form = document.createElement('form');
const submit = document.createElement('button');
submit.textContent = 'Speichern';
form.append(submit);
document.body.append(form);

const setUploading = (busy) => {
  submit.setCustomValidity(busy ? 'Der Upload läuft noch – bitte warten.' : '');
};

setUploading(true);
console.log(form.checkValidity()); // Das Formular ist ungültig
submit.reportValidity();           // Die Sprechblase erscheint am Button

setTimeout(() => {
  setUploading(false);
  console.log(form.checkValidity());
}, 1000);

false true

Wirkungslos bei type="button"

const plain = document.createElement('button');
plain.type = 'button';
plain.setCustomValidity('Fehler');

console.log(plain.willValidate);       // von der Validierung ausgeschlossen
console.log(plain.validationMessage);  // leer, weil das Element nicht validiert wird
console.log(plain.checkValidity());

false true

// Wichtig · Fallstricke

Der Fehler bleibt bestehen: Er verschwindet nicht von selbst. Sie müssen ihn ausdrücklich mit setCustomValidity('') aufheben, sonst lässt sich das Formular dauerhaft nicht absenden.
Nur Absende-Buttons werden validiert: Bei type="button", type="reset", deaktivierten Buttons (disabled) und Buttons innerhalb eines <datalist> hat die Meldung keine Wirkung.
Parameter ist Pflicht: Ein Aufruf ohne Argument löst einen TypeError aus. Zum Aufheben also immer '' übergeben, nicht null, denn daraus wird der Text "null".
novalidate hebelt die Prüfung aus: Hat das Formular das Attribut novalidate oder der Button formnovalidate, wird trotz Fehler abgesendet.
Darstellung: Aussehen und Dauer der Sprechblase legt der Browser fest und lassen sich nicht gestalten. Schreiben Sie kurze Meldungen. Für Barrierefreiheit und eigenes Design zeigen Sie den Fehler zusätzlich im DOM an, zum Beispiel über aria-describedby.
Keine Sicherheitsmaßnahme: Die Prüfung im Browser lässt sich leicht umgehen. Prüfen Sie Bedingungen immer auch auf dem Server.
Browser-Kompatibilität: Wird von allen aktuellen Browsern unterstützt.

Siehe auch

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