Element.ariaInvalid — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaInvalid

Beschreibung

Die Eigenschaft ariaInvalid gehört zum ARIA-Reflection-Mechanismus der Element-Schnittstelle. Sie spiegelt das HTML-Attribut aria-invalid direkt wider: Liest man die Eigenschaft, erhält man den Attributwert als Zeichenkette. Setzt man sie, wird das Attribut geschrieben. Mit null wird das Attribut entfernt.

Mit aria-invalid teilt man Screenreadern und anderen Hilfstechnologien mit, dass der eingegebene Wert eines Formularfelds nicht den erwarteten Vorgaben entspricht. Das ist vor allem bei eigener, per JavaScript umgesetzter Validierung wichtig, weil sich der Fehlerzustand sonst nur optisch zeigt.

Erlaubte Werte sind:

"true": Der Wert ist ungültig.
"false": Kein Fehler erkannt (Standardverhalten).
"grammar": Es wurde ein Grammatikfehler erkannt.
"spelling": Es wurde ein Rechtschreibfehler erkannt.

Unbekannte Werte werden von Hilfstechnologien wie "true" behandelt. Setzen Sie aria-invalid erst, nachdem der Nutzer eine Eingabe gemacht oder das Formular abgeschickt hat, und nicht schon beim Laden der Seite.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Neuer Wert beim Setzen: `"true"`, `"false"`, `"grammar"` oder `"spelling"`. Mit `null` wird das Attribut entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des aria-invalid-Attributs als Zeichenkette oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Wert lesen und setzen

// HTML: <input id="email" type="email" aria-invalid="false">
const input = document.getElementById('email');

console.log(input.ariaInvalid);
input.ariaInvalid = 'true';
console.log(input.getAttribute('aria-invalid'));

false true

Fehlerzustand bei eigener Validierung melden

// HTML:
// <input id="plz" aria-describedby="plz-fehler">
// <p id="plz-fehler" hidden>Bitte eine fünfstellige Postleitzahl eingeben.</p>
const plz = document.getElementById('plz');
const fehler = document.getElementById('plz-fehler');

const pruefen = () => {
  const gueltig = /^\d{5}$/.test(plz.value);
  plz.ariaInvalid = gueltig ? 'false' : 'true';
  fehler.hidden = gueltig;
};

// Erst nach dem Verlassen des Feldes prüfen, nicht bei jedem Tastendruck
plz.addEventListener('blur', pruefen);

Attribut wieder entfernen

const feld = document.querySelector('#name');
feld.ariaInvalid = 'true';

// Formular zurückgesetzt: Zustand vollständig entfernen
feld.ariaInvalid = null;
console.log(feld.hasAttribute('aria-invalid'));
console.log(feld.ariaInvalid);

false null

Browserunterstützung prüfen und Fallback nutzen

const setInvalid = (el, wert) => {
  if ('ariaInvalid' in Element.prototype) {
    el.ariaInvalid = wert;
  } else {
    el.setAttribute('aria-invalid', wert);
  }
};

setInvalid(document.querySelector('#passwort'), 'true');

// Wichtig · Fallstricke

Nur Zeichenketten: Die Eigenschaft gibt immer einen String zurück und keinen Boolean. if (el.ariaInvalid) ist auch bei "false" wahr. Vergleichen Sie deshalb ausdrücklich mit === 'true'.
Kein Einfluss auf die Formularvalidierung: ariaInvalid ändert weder validity noch checkValidity() und setzt auch nicht die CSS-Pseudoklasse :invalid. Zum Gestalten eignet sich der Attributselektor [aria-invalid="true"]. Für die native Validierung nutzen Sie setCustomValidity().
Doppelte Angaben vermeiden: Bei nativen Feldern mit required oder pattern melden Browser Fehler teilweise schon selbst. Achten Sie darauf, dass sich aria-invalid und der native Zustand nicht widersprechen.
Fehlertext verknüpfen: aria-invalid sagt nur, dass ein Fehler vorliegt, aber nicht, welcher. Verknüpfen Sie deshalb eine Fehlermeldung über aria-describedby oder aria-errormessage.
Kompatibilität: Chromium und Safari unterstützen ARIA-Reflection schon lange, Firefox erst ab Version 119. Für ältere Browser verwenden Sie setAttribute('aria-invalid', …).

Siehe auch

Element.ariaDisabled Element.ariaLevel Element.ariaModal Element.ariaAtomic Element.ariaChecked