HTMLTextAreaElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLTextAreaElement.prototype.setCustomValidity(message)

Beschreibung

Mit setCustomValidity() legst du für ein <textarea> einen eigenen Validierungsfehler fest. Ist die Meldung ein nicht leerer String, gilt das Element als ungültig: validity.customError wird true, validity.valid wird false und die CSS-Pseudoklasse :invalid greift. Beim Absenden des Formulars blockiert der Browser den Versand und zeigt die Meldung in seiner eingebauten Fehlerblase an.

Die Methode lohnt sich überall dort, wo die eingebauten Attribute wie required, minlength oder maxlength nicht reichen. Beispiele sind Wortzahlgrenzen, verbotene Begriffe, eine Prüfung gegen ein anderes Feld oder eine serverseitige Rückmeldung (etwa „Dieser Text wurde bereits eingereicht“).

Wichtig: Der benutzerdefinierte Fehler bleibt so lange bestehen, bis du ihn ausdrücklich mit setCustomValidity('') löschst. Er verschwindet nicht von selbst, wenn der Nutzer weitertippt. Üblich ist deshalb, die Prüfung im input-Event zu erledigen und die Meldung dort je nach Ergebnis zu setzen oder zu leeren. Nutze reportValidity(), wenn die Meldung sofort und nicht erst beim Absenden erscheinen soll.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Fehlermeldung, die angezeigt werden soll. Ein nicht leerer String macht das Element ungültig, ein leerer String (`''`) entfernt den benutzerdefinierten Fehler. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Höchstzahl an Wörtern prüfen

// HTML: <form><textarea id="bio" name="bio"></textarea><button>Senden</button></form>
const bio = document.querySelector('#bio');
const MAX_WORDS = 50;

bio.addEventListener('input', () => {
  const words = bio.value.trim().split(/\s+/).filter(Boolean).length;
  if (words > MAX_WORDS) {
    bio.setCustomValidity(`Bitte höchstens ${MAX_WORDS} Wörter (aktuell ${words}).`);
  } else {
    bio.setCustomValidity(''); // Fehler wieder löschen – sonst bleibt das Feld ungültig
  }
});

Verbotene Begriffe und sofortige Anzeige mit reportValidity()

const comment = document.querySelector('textarea[name="comment"]');
const forbidden = ['spam', 'werbung'];

comment.addEventListener('blur', () => {
  const hit = forbidden.find((w) => comment.value.toLowerCase().includes(w));
  comment.setCustomValidity(hit ? `Der Begriff „${hit}“ ist nicht erlaubt.` : '');
  comment.reportValidity(); // zeigt die Fehlerblase sofort an
  console.log(comment.validity.customError, comment.validationMessage);
});

true Der Begriff „spam“ ist nicht erlaubt.

Fehlermeldung vom Server übernehmen

const form = document.querySelector('#feedback-form');
const message = form.elements.message;

// Fehler zurücksetzen, sobald der Nutzer den Text ändert
message.addEventListener('input', () => message.setCustomValidity(''));

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const res = await fetch('/api/feedback', {
    method: 'POST',
    body: new FormData(form),
  });
  if (!res.ok) {
    const { error } = await res.json(); // z. B. { error: 'Text zu kurz' }
    message.setCustomValidity(error);
    message.reportValidity();
    return;
  }
  form.reset();
});

// Wichtig · Fallstricke

Häufigster Fehler: Wer vergisst, setCustomValidity('') aufzurufen, hat ein Feld, das dauerhaft ungültig bleibt. Das Formular lässt sich dann nie absenden, auch wenn die Eingabe inzwischen korrekt ist.
Benutzerdefinierte Fehler werden gemeinsam mit den eingebauten Prüfungen (required, minlength …) ausgewertet. validationMessage zeigt dabei den benutzerdefinierten Fehler bevorzugt an.
Hat das Formular das Attribut novalidate oder der Button formnovalidate, zeigt der Browser keine Fehlerblase an und blockiert das Absenden nicht. checkValidity() meldet das Feld aber weiterhin als ungültig.
Bei disabled- oder readonly-Textfeldern findet keine Validierung statt (sie sind vom „constraint validation“ ausgenommen).
Aussehen und Anzeigedauer der Fehlerblase legt der Browser fest und lassen sich nicht gestalten. Für eigene Fehler-Oberflächen prüfst du validity bzw. validationMessage und fängst das invalid-Event mit preventDefault() ab.
Barrierefreiheit: Sinnvoll ist es, zusätzlich aria-invalid und einen sichtbaren Fehlertext mit aria-describedby zu setzen.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Baseline).

Siehe auch

HTMLTextAreaElement.reportValidity() HTMLTextAreaElement.checkValidity() HTMLTextAreaElement.select() HTMLTextAreaElement.setRangeText() HTMLTextAreaElement.setSelectionRange()