Signatur
Beschreibung
Die Eigenschaft ariaErrorMessageElements ist das DOM-Gegenstück zum ARIA-Attribut aria-errormessage, das sich direkt auf Elemente bezieht. Das Attribut erwartet eine durch Leerzeichen getrennte Liste von id-Werten. Die Eigenschaft dagegen nimmt ein Array aus echten Element-Objekten entgegen. Es gibt also keine IDs, die man vergeben und pflegen muss, und keine Tippfehler in ID-Referenzen.
Assistive Technologien wie Screenreader lesen den Inhalt der verknüpften Elemente als Fehlermeldung vor. Das geschieht aber nur, wenn das Element gleichzeitig als ungültig markiert ist (aria-invalid="true" bzw. ariaInvalid = "true"). Typischer Einsatz: Formularvalidierung, bei der ein Eingabefeld mit einer sichtbaren Fehlermeldung verbunden wird.
Besonders nützlich ist die Eigenschaft bei Web Components und dynamisch erzeugtem DOM. Die verknüpften Elemente dürfen in einem übergeordneten Scope liegen, etwa im Light DOM, wenn das Element im Shadow DOM sitzt. Über IDs lässt sich so eine Verknüpfung über Shadow-Grenzen hinweg nicht herstellen. Wird der Eigenschaft ein Wert zugewiesen, wird das Inhaltsattribut aria-errormessage auf einen leeren String gesetzt. Setzt man null, wird die Verknüpfung entfernt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | Element[] | null | null | Beim Setzen: ein Array von Elementen, die die Fehlermeldung enthalten, oder null, um die Verknüpfung zu entfernen. |
Rückgabewert
null. Wurde aria-errormessage per Attribut gesetzt, enthält das Array die Elemente, die über die angegebenen IDs gefunden werden.Beispiele
Eingabefeld mit Fehlermeldung verknüpfen
// HTML: <input id="email" type="email"> <p id="email-fehler" hidden></p>
const input = document.querySelector('#email');
const fehler = document.querySelector('#email-fehler');
input.ariaErrorMessageElements = [fehler];
input.addEventListener('blur', () => {
const ungueltig = !input.validity.valid;
input.ariaInvalid = String(ungueltig);
fehler.hidden = !ungueltig;
fehler.textContent = ungueltig ? 'Bitte eine gültige E-Mail-Adresse eingeben.' : '';
});
console.log(input.ariaErrorMessageElements[0].id);Verknüpfung auslesen und wieder entfernen
const feld = document.querySelector('#email');
const elemente = feld.ariaErrorMessageElements ?? [];
console.log(elemente.map((el) => el.textContent));
// Fehler behoben: Verknüpfung entfernen
feld.ariaInvalid = 'false';
feld.ariaErrorMessageElements = null;
console.log(feld.ariaErrorMessageElements);Referenz über die Shadow-DOM-Grenze hinweg
// HTML: <span id="globaler-fehler">Pflichtfeld</span> <mein-feld></mein-feld>
class MeinFeld extends HTMLElement {
connectedCallback() {
const root = this.attachShadow({ mode: 'open' });
const input = document.createElement('input');
root.append(input);
// Verweis vom Shadow DOM auf ein Element im Light DOM – mit IDs nicht möglich
input.ariaInvalid = 'true';
input.ariaErrorMessageElements = [document.getElementById('globaler-fehler')];
}
}
customElements.define('mein-feld', MeinFeld);Funktionsprüfung mit Rückfall auf das Attribut
const verknuepfeFehler = (input, fehlerEl) => {
if ('ariaErrorMessageElements' in Element.prototype) {
input.ariaErrorMessageElements = [fehlerEl];
} else {
fehlerEl.id ||= `fehler-${crypto.randomUUID()}`;
input.setAttribute('aria-errormessage', fehlerEl.id);
}
};
verknuepfeFehler(document.querySelector('#email'), document.querySelector('#email-fehler'));// Wichtig · Fallstricke
- Nur zusammen mit
aria-invalid: Screenreader kündigen die Fehlermeldung nur an, wenn das Element auch als ungültig markiert ist. Solange kein Fehler vorliegt, sollte das Fehlermeldungs-Element versteckt sein. - Eingefrorenes Array: Das zurückgegebene Array lässt sich nicht verändern.
push()wirft im Strict Mode einen Fehler. Um Elemente zu ändern, weist man immer ein neues Array zu. - Scope-Einschränkung: Verknüpfte Elemente müssen im selben Baum oder in einem übergeordneten Scope liegen. Verweise von außen in ein Shadow DOM hinein werden nicht aufgelöst und fehlen dann im Getter-Ergebnis.
- Attribut und Eigenschaft: Nach dem Setzen der Eigenschaft steht im Attribut
aria-errormessageein leerer String und nicht die IDs. Beim Serialisieren des DOM (z. B. mitouterHTML) geht die Verknüpfung deshalb verloren. - Unterstützung durch Screenreader:
aria-errormessagewird noch nicht von allen Screenreadern zuverlässig vorgelesen. Viele Entwickler setzen deshalb zusätzlichariaDescribedByElementsoder eine Live-Region (role="alert") ein. - Browser-Unterstützung: Die Eigenschaft gehört zu den ARIA-Reflexionen mit Element-Referenzen. Safari unterstützt sie seit 16.4, Chrome/Edge seit 135 und Firefox seit 136. Für ältere Browser ist eine Funktionsprüfung nötig, siehe Beispiel 4.