Signatur
Beschreibung
Die Eigenschaft ariaLabelledByElements gehört zur ARIA-Reflexion mit Elementreferenzen (ARIAMixin). Sie enthält ein Array von Element-Objekten, aus deren Text Hilfstechnologien wie Screenreader den zugänglichen Namen (accessible name) des Elements berechnen. Das Ergebnis ist dasselbe wie beim Attribut aria-labelledby. Dort stehen aber durch Leerzeichen getrennte IDs, hier echte Objektreferenzen.
Der größte Vorteil: Die Elemente brauchen keine ID. Das ist besonders in Web Components mit Shadow DOM nützlich. Eine ID-Referenz über aria-labelledby kann die Grenze eines Shadow Roots nicht überschreiten. Eine Elementreferenz über diese Eigenschaft kann dagegen auf Elemente in einem übergeordneten Scope zeigen, also im Light DOM oder in einem umgebenden Shadow Root.
Beim Lesen erhältst du ein eingefrorenes Array der gültigen Referenzen oder null. Mit einem Array setzt du die Referenzen. Mit null entfernt eine Zuweisung sie. Wenn du die Eigenschaft setzt, leert der Browser den Wert des Attributs aria-labelledby (das Attribut bleibt als leere Zeichenkette stehen). Setzt du dagegen das Attribut, gelten wieder die ID-Referenzen. Die Reihenfolge im Array bestimmt, in welcher Reihenfolge die Texte zum Namen zusammengesetzt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | Array<Element> | null | null | Wird beim Setzen zugewiesen: ein Array von Elementen, deren Textinhalt nacheinander den zugänglichen Namen bildet. Mit null werden die Referenzen entfernt. |
Rückgabewert
null zurück. Hat nur das Attribut aria-labelledby gültige IDs, liefert die Eigenschaft die über diese IDs aufgelösten Elemente.Beispiele
Beschriftung ohne ID zuweisen
// Ein Dialog soll seinen Namen aus der Überschrift beziehen
const dialog = document.createElement('div');
dialog.setAttribute('role', 'dialog');
const heading = document.createElement('h2');
heading.textContent = 'Einstellungen';
dialog.append(heading);
document.body.append(dialog);
// Direkte Elementreferenz statt ID
dialog.ariaLabelledByElements = [heading];
console.log(dialog.ariaLabelledByElements[0].textContent);
console.log(dialog.getAttribute('aria-labelledby'));Namen aus mehreren Elementen zusammensetzen
// HTML: <span id="produkt">Laptop X1</span>
// <span id="preis">999 €</span>
// <button id="kaufen">Kaufen</button>
const button = document.querySelector('#kaufen');
const produkt = document.querySelector('#produkt');
const preis = document.querySelector('#preis');
// Reihenfolge bestimmt den zugänglichen Namen: "Kaufen Laptop X1 999 €"
button.ariaLabelledByElements = [button, produkt, preis];
console.log(button.ariaLabelledByElements.map((el) => el.textContent).join(' '));Web Component: Label aus dem Light DOM referenzieren
class FancyInput extends HTMLElement {
#input;
constructor() {
super();
const shadow = this.attachShadow({ mode: 'open' });
this.#input = document.createElement('input');
shadow.append(this.#input);
}
// Label-Element von außen übergeben
set labelElement(el) {
// Funktioniert über die Shadow-Grenze hinweg (von innen nach außen)
this.#input.ariaLabelledByElements = el ? [el] : null;
}
}
customElements.define('fancy-input', FancyInput);
const label = document.createElement('span');
label.textContent = 'E-Mail-Adresse';
const field = document.createElement('fancy-input');
document.body.append(label, field);
field.labelElement = label;Feature-Erkennung und Zurücksetzen
const el = document.querySelector('[role="region"]');
if ('ariaLabelledByElements' in Element.prototype) {
el.ariaLabelledByElements = [document.querySelector('h2')];
// Später entfernen
el.ariaLabelledByElements = null;
console.log(el.ariaLabelledByElements);
} else {
// Fallback über ID-Referenz
const h2 = document.querySelector('h2');
h2.id ||= 'region-titel';
el.setAttribute('aria-labelledby', h2.id);
}// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Eigenschaft ist erst seit Kurzem in allen großen Browsern verfügbar: Safari 16.4, Chrome/Edge 135, Firefox 136. Für ältere Browser brauchst du eine Feature-Erkennung und als Fallback das Attribut
aria-labelledbymit IDs. - Shadow-DOM-Regel: Du kannst nur auf Elemente im selben Baum oder in einem übergeordneten Scope verweisen. Eine Referenz von außen in einen Shadow Root hinein ist ungültig und wird beim Lesen herausgefiltert.
- Eingefrorenes Array: Das zurückgegebene Array kannst du nicht verändern.
push()wirft im Strict Mode einen Fehler. Weise für Änderungen immer ein neues Array zu. - Attribut vs. Eigenschaft: Wenn du die Eigenschaft setzt, leert der Browser den Wert von
aria-labelledby. Ein späteressetAttribute('aria-labelledby', …)überschreibt dafür die Elementreferenzen. Mische beide Wege nicht. - Die Elemente werden über schwache Referenzen gehalten. Wird ein referenziertes Element aus dem Dokument entfernt, taucht es beim Lesen nicht mehr auf.
aria-labelledbyhat bei der Namensberechnung Vorrang voraria-labelund vor nativen<label>-Elementen. Verwende es nur, wenn keine native Beschriftung passt.