ElementInternals.reportValidity() — Methode · JavaScript-Referenz

Signatur

ElementInternals.prototype.reportValidity()

Beschreibung

reportValidity() gehört zur ElementInternals-Schnittstelle. Mit ihr klinken sich formularassoziierte Custom Elements (static formAssociated = true) in die eingebaute Formularvalidierung des Browsers ein. Die Methode prüft den Gültigkeitszustand, den du vorher mit internals.setValidity() gesetzt hast. Ist das Element ungültig, feuert sie am Host-Element ein abbrechbares invalid-Event. Wird dieses Event nicht abgebrochen, zeigt der Browser die Fehlermeldung an, meist als Tooltip am Element oder am mit setValidity() übergebenen Anker.

Der Unterschied zu checkValidity(): checkValidity() meldet das Ergebnis nur still als Rückgabewert und löst dabei ebenfalls invalid aus. reportValidity() zeigt den Fehler zusätzlich sichtbar an. Deshalb passt die Methode gut zu eigener Absende-Logik, zum Beispiel bei novalidate-Formularen, Assistenten mit mehreren Schritten oder einer Prüfung beim Verlassen des Feldes (blur).

Die Methode liest nur den Zustand, den setValidity() festgelegt hat. Eigene Regeln wie „Pflichtfeld“ musst du also selbst in setValidity() umsetzen, bevor du reportValidity() aufrufst.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element gültig ist oder nicht validiert wird. false, wenn es ungültig ist. In diesem Fall wurde ein invalid-Event ausgelöst und, sofern es nicht abgebrochen wurde, die Fehlermeldung angezeigt.

Beispiele

Custom Element mit Pflichtfeld-Prüfung

class RatingInput extends HTMLElement {
  static formAssociated = true;
  #internals = this.attachInternals();
  #value = 0;

  connectedCallback() {
    this.tabIndex = 0;
    this.#validate();
  }

  set value(v) {
    this.#value = Number(v);
    this.#internals.setFormValue(String(this.#value));
    this.#validate();
  }

  #validate() {
    if (this.#value < 1) {
      this.#internals.setValidity({ valueMissing: true }, 'Bitte mindestens 1 Stern vergeben.');
    } else {
      this.#internals.setValidity({});
    }
  }

  // Öffentliche API, wie bei nativen Eingabefeldern
  reportValidity() {
    return this.#internals.reportValidity();
  }
}
customElements.define('rating-input', RatingInput);

const el = document.createElement('rating-input');
document.body.append(el);
console.log(el.reportValidity()); // zeigt Tooltip
el.value = 4;
console.log(el.reportValidity());

false true

Eigene Absende-Logik mit novalidate-Formular

// <form id="f" novalidate><rating-input name="stars"></rating-input><button>Senden</button></form>
const form = document.querySelector('#f');
const rating = form.querySelector('rating-input');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (!rating.reportValidity()) return; // Fehler wird angezeigt
  const data = new FormData(form);
  await fetch('/api/bewertung', { method: 'POST', body: data });
  console.log('Gesendet:', data.get('stars'));
});

invalid-Event abfangen und eigene Fehleranzeige nutzen

const field = document.querySelector('rating-input');
const errorBox = document.querySelector('#rating-error');

field.addEventListener('invalid', (event) => {
  event.preventDefault(); // Browser-Tooltip unterdrücken
  errorBox.textContent = field.validationMessage ?? 'Ungültige Eingabe';
});

field.addEventListener('blur', () => {
  if (field.reportValidity()) errorBox.textContent = '';
});

// Wichtig · Fallstricke

Nur für formularassoziierte Elemente: Fehlt static formAssociated = true, wirft der Aufruf eine NotSupportedError-DOMException.
Kein automatischer Proxy: Das Host-Element hat selbst keine Methode reportValidity(). Du musst sie wie im Beispiel selbst anbieten, wenn Code außerhalb sie aufrufen soll. validationMessage und validity brauchst du ebenfalls als eigene Getter, die an internals weiterreichen.
Nur für einen gesetzten Zustand: Die Methode wertet nur aus, was du vorher mit setValidity() festgelegt hast. Das Attribut required am Custom Element prüft der Browser nicht selbst.
Anker für den Tooltip: Übergib als drittes Argument von setValidity() ein fokussierbares Element im Shadow DOM, damit der Tooltip an der richtigen Stelle erscheint und der Fokus dort landet.
Nicht in Schleifen aufrufen: Mehrere reportValidity()-Aufrufe hintereinander verschieben jedes Mal den Fokus und erzeugen neue Tooltips. Nutze für stille Prüfungen checkValidity().
Browser-Unterstützung: In Safari erst ab Version 16.4 verfügbar. Für ältere Browser gibt es das Polyfill element-internals-polyfill.

Siehe auch

ElementInternals.setValidity() ElementInternals.checkValidity() ElementInternals.setFormValue() HTMLInputElement.reportValidity() HTMLOutputElement.reportValidity()