HTMLFieldSetElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLFieldSetElement.prototype.setCustomValidity(message)

Beschreibung

Die Methode setCustomValidity() gehört zur Constraint Validation API und setzt für ein <fieldset> eine eigene Fehlermeldung. Übergibt man einen nicht leeren String, gilt für das Element ein benutzerdefinierter Fehler: fieldset.validity.customError wird true. Mit einem leeren String ("") wird der Fehler zurückgesetzt.

Wichtige Besonderheit: Ein <fieldset> ist laut HTML-Spezifikation kein Kandidat für die Constraint-Validierung (willValidate ist immer false). Deshalb verhindert ein hier gesetzter Fehler das Absenden des Formulars nicht. Außerdem liefern checkValidity() und reportValidity() weiterhin true, validationMessage bleibt leer, und der Browser zeigt keine Fehler-Sprechblase an.

Die Methode gibt es auf HTMLFieldSetElement vor allem, damit alle formularbezogenen Elemente dieselbe Schnittstelle haben. Gebraucht wird sie selten, z. B. um sich intern einen Gruppenfehler zu merken. Wenn eine ganze Gruppe als ungültig gelten soll (etwa „mindestens eine Checkbox auswählen“), setzt man den Fehler in der Praxis auf ein Eingabeelement innerhalb des fieldsets. Das fieldset selbst passt über die Pseudoklasse :invalid sein Aussehen automatisch an, sobald eines seiner Nachfahren-Elemente ungültig ist.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Fehlermeldung. Ein nicht leerer String markiert das Element als fehlerhaft (`customError`), ein leerer String `""` entfernt den Fehler. Andere Werte werden in einen String umgewandelt, z. B. `null` zu `"null"`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Eigenen Fehler setzen und prüfen

// <fieldset id="adresse"><input name="plz"></fieldset>
const fs = document.querySelector('#adresse');

fs.setCustomValidity('Adresse unvollständig');

console.log(fs.validity.customError); // Fehler ist gesetzt
console.log(fs.willValidate);         // fieldset wird nie validiert
console.log(fs.checkValidity());      // blockiert daher nichts
console.log(JSON.stringify(fs.validationMessage));

// Fehler zurücksetzen
fs.setCustomValidity('');
console.log(fs.validity.customError);

true false true "" false

Praxis: Checkbox-Gruppe prüfen, Fehler auf ein Kind-Element setzen

// <form id="f">
//   <fieldset id="themen">
//     <legend>Interessen (mind. eine)</legend>
//     <label><input type="checkbox" name="t" value="js"> JS</label>
//     <label><input type="checkbox" name="t" value="css"> CSS</label>
//   </fieldset>
//   <button>Senden</button>
// </form>
const form = document.querySelector('#f');
const fs = document.querySelector('#themen');
const boxes = [...fs.querySelectorAll('input[type=checkbox]')];

const pruefeGruppe = () => {
  const ok = boxes.some((b) => b.checked);
  // Nur Kind-Elemente blockieren das Absenden
  boxes[0].setCustomValidity(ok ? '' : 'Bitte mindestens ein Thema wählen.');
};

fs.addEventListener('change', pruefeGruppe);
pruefeGruppe();

form.addEventListener('submit', (e) => {
  if (!form.reportValidity()) e.preventDefault();
  console.log('fieldset :invalid?', fs.matches(':invalid'));
});

fieldset :invalid? true (solange keine Checkbox gewählt ist)

Gruppenstatus am fieldset merken und per CSS-Klasse anzeigen

const fs = document.querySelector('#zahlung');

const setzeGruppenfehler = (text) => {
  fs.setCustomValidity(text);
  // fieldset erhält kein :invalid durch eigenen customError → Klasse selbst setzen
  fs.classList.toggle('fehler', fs.validity.customError);
  fs.querySelector('.meldung').textContent = text;
};

setzeGruppenfehler('Bitte eine Zahlungsart wählen.');
console.log(fs.classList.contains('fehler'));

true

// Wichtig · Fallstricke

Blockiert das Absenden nicht: <fieldset> ist von der Constraint-Validierung ausgeschlossen. checkValidity() und reportValidity() geben true zurück, validationMessage ist leer, und es erscheint keine Browser-Meldung. Soll das Absenden verhindert werden, setzt man den Fehler auf ein <input>, <select> o. Ä. innerhalb des fieldsets.
Nur die Kinder bestimmen :invalid: Das fieldset passt auf :invalid, wenn ein Nachfahren-Element ungültig ist, nicht wegen des eigenen customError. Das kann sich je nach Browser leicht unterscheiden.
Zurücksetzen nicht vergessen: Der Fehler bleibt gesetzt, bis setCustomValidity('') aufgerufen wird. Bei Kind-Elementen führt ein vergessenes Zurücksetzen dazu, dass sich das Formular nie absenden lässt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Die Meldung ist reiner Text, HTML darin wird nicht interpretiert.

Siehe auch

HTMLFieldSetElement.reportValidity() HTMLFieldSetElement.checkValidity() HTMLSelectElement.setCustomValidity() HTMLInputElement.setCustomValidity() HTMLObjectElement.setCustomValidity()