Eigenschaft Beziehung

`aria-labelledby`

Referenziert eine oder mehrere Element-IDs, deren sichtbarer Text zum barrierefreien Namen dieses Elements wird. Wird aria-label vorgezogen, wenn auf dem Bildschirm bereits Text vorhanden ist, der das Steuerelement beschreibt.

Wann zu verwenden

Wenn ein sichtbares Textelement auf der Seite bereits das Element beschreibt — eine Überschrift über einem Dialog, ein Spaltenheader über einer Zelle, ein Absatz, der einen Bereich einleitet. aria-labelledby zeigt auf diesen Text, damit der Screenreader ihn als barrierefreien Namen des Elements ankündigt. Die Nutzenden hören genau das, was sehende Nutzende lesen.

Das native HTML-Äquivalent ist <label for="…"> bei Formulareingaben. aria-labelledby erweitert dieselbe Idee auf jede Rolle, die einen Namen unterstützt.

Verhalten

Der Wert ist eine leerzeichengetrennte Liste von Element-IDs. Die assistive Technologie sammelt den Textinhalt jedes referenzierten Elements, in der angegebenen Reihenfolge, verbindet ihn mit Leerzeichen und verwendet das Ergebnis als barrierefreien Namen. Referenzen auf ausgeblendete Elemente (display: none, hidden) tragen ihren Text trotzdem bei — das Element muss lediglich im DOM vorhanden sein.

aria-labelledby hat Vorrang vor aria-label, welches wiederum Vorrang vor sichtbarem Inhaltstext hat. Wird also auf die sichtbare Überschrift gezeigt, ist kein zusätzliches aria-label erforderlich.

Damit die Beziehung gültig bleibt: Die referenzierten IDs müssen auf der Seite vorhanden und eindeutig sein, und der Text darin muss aussagekräftig bleiben. Wird ein Tab-Panel neu gerendert und dabei IDs wiederverwendet, sollte geprüft werden, ob der neue Inhalt das beschriftete Element noch korrekt beschreibt.

Häufige Fehler

Auf eine ID zeigen, die nicht existiert (Tippfehler, Element entfernt, Komponente ausgehängt). Die Beziehung schlägt lautlos fehl, und das Element bleibt ohne Namen.
Dieselbe ID zweimal auf einer Seite verwenden — nur der erste Treffer zählt.
Auf ein Element verweisen, dessen Text leer ist oder nur aus Leerzeichen besteht.
Falsche Reihenfolge bei der Verkettung: aria-labelledby="nachname vorname" ergibt „Müller Hans“, wenn „Hans Müller“ gewünscht war.
Auf ein generisches <div> zeigen, das einen langen Absatz enthält — der gesamte Absatz wird zum Namen. Namen sollten kurz sein; längerer Kontext gehört in aria-describedby.
Vergessen, den referenzierten Text bei der Lokalisierung zu aktualisieren — Namen geraten aus dem Takt mit der sichtbaren Benutzeroberfläche.

Beispiel

<h2 id="billing-heading">Rechnungsadresse</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Straße
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- Zwei IDs verkettet für ein Vor- und Nachname-Muster -->
<span id="first">Vorname</span>
<span id="last">(erforderlich)</span>
<input type="text" aria-labelledby="first last">