Element.ariaLabel — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaLabel

Beschreibung

Die Eigenschaft ariaLabel gehört zum ARIAMixin und steht deshalb auf jedem Element zur Verfügung. Sie spiegelt das HTML-Attribut aria-label. Liest man die Eigenschaft, erhält man den aktuellen Attributwert. Schreibt man sie, wird das Attribut gesetzt. Mit null wird das Attribut entfernt.

Über aria-label bekommt ein Element einen zugänglichen Namen, den Screenreader vorlesen. Das braucht man vor allem bei Bedienelementen ohne sichtbaren Text, zum Beispiel bei Icon-Buttons („Schließen“, „Suchen“), bei Navigationsbereichen mit mehreren <nav>-Elementen oder bei Eingabefeldern ohne <label>.

Die Eigenschaft ist praktischer als setAttribute('aria-label', …), wenn sich die Beschriftung zur Laufzeit ändert, etwa bei Umschaltknöpfen, deren Aktion vom Zustand abhängt („Menü öffnen“ bzw. „Menü schließen“). Ist sichtbarer Text vorhanden, verweist man besser mit aria-labelledby auf ihn oder nutzt ein natives <label>.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null		Beim Schreiben: der neue Beschriftungstext. `null` entfernt das Attribut `aria-label`.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-label. Ist das Attribut nicht gesetzt, ist der Wert null.

Beispiele

Beschriftung lesen und setzen

// <button id="close">✕</button>
const btn = document.querySelector('#close');
console.log(btn.ariaLabel); // Attribut fehlt noch

btn.ariaLabel = 'Dialog schließen';
console.log(btn.ariaLabel);
console.log(btn.getAttribute('aria-label'));

null Dialog schließen Dialog schließen

Umschaltknopf mit zustandsabhängiger Beschriftung

// <button id="menu-toggle" aria-expanded="false" aria-label="Menü öffnen">☰</button>
const toggle = document.querySelector('#menu-toggle');
const menu = document.querySelector('#main-menu');

toggle.addEventListener('click', () => {
  const open = toggle.ariaExpanded === 'true';
  toggle.ariaExpanded = String(!open);
  toggle.ariaLabel = open ? 'Menü öffnen' : 'Menü schließen';
  menu.hidden = open;
});

Attribut wieder entfernen

const nav = document.createElement('nav');
nav.ariaLabel = 'Seitennavigation';
console.log(nav.outerHTML);

nav.ariaLabel = null; // entfernt das Attribut
console.log(nav.hasAttribute('aria-label'));

<nav aria-label="Seitennavigation"></nav> false

Fehlende Beschriftungen bei Icon-Buttons finden

const unlabeled = [...document.querySelectorAll('button')]
  .filter((b) => !b.textContent.trim() && !b.ariaLabel && !b.hasAttribute('aria-labelledby'));

console.log(`${unlabeled.length} Buttons ohne zugänglichen Namen`);

z. B. "2 Buttons ohne zugänglichen Namen"

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome/Edge und Safari unterstützen die Eigenschaft seit Langem, Firefox erst ab Version 119. Für ältere Browser ist setAttribute('aria-label', …) die sichere Alternative.
Fehlendes Attribut: Ohne gesetztes Attribut ist der Wert null, nicht ''. Ein leerer String bleibt als leeres Attribut stehen. Zum Entfernen setzt man null.
Vorrang: aria-labelledby hat Vorrang vor aria-label. Außerdem überschreibt aria-label den sichtbaren Inhalt als zugänglichen Namen. Weichen beide voneinander ab, haben Nutzer von Sprachsteuerung Probleme (WCAG 2.5.3 „Label in Name“).
Bei generischen Elementen ohne Rolle, etwa <div> oder <span>, wird aria-label von vielen Screenreadern ignoriert. Solche Elemente brauchen zuerst eine passende role.
Einige Übersetzungsdienste übersetzen aria-label nicht mit. Wo es möglich ist, sind sichtbare oder visuell versteckte Texte die robustere Lösung.

Siehe auch

Element.role Element.ariaModal Element.ariaLevel Element.ariaLive Element.ariaBusy