Element.ariaDescription — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaDescription

Beschreibung

Die Eigenschaft ariaDescription spiegelt das HTML-Attribut aria-description direkt wider (sogenannte ARIA-Reflection). Über sie gibst du einem Element eine zugängliche Beschreibung. Das ist ein ergänzender Hinweistext, den Screenreader meist nach dem Namen und der Rolle des Elements vorlesen.

Anders als aria-describedby verweist aria-description nicht auf ein anderes Element, sondern enthält den Text selbst. Das passt gut, wenn der Beschreibungstext nicht sichtbar auf der Seite stehen soll oder dort gar nicht vorkommt, zum Beispiel bei Hinweisen zu Tastenkürzeln, bei Kontext zu Symbol-Schaltflächen oder bei dynamischen Statusangaben.

Beim Lesen erhältst du den aktuellen Attributwert als Zeichenkette oder null, wenn das Attribut fehlt. Beim Schreiben wird das Attribut gesetzt. Setzt du null, wird das Attribut entfernt. el.ariaDescription = 'x' wirkt also genauso wie el.setAttribute('aria-description', 'x'), ist aber kürzer und besser lesbar.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der neue Beschreibungstext. `null` entfernt das Attribut `aria-description`.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-description. null, wenn das Attribut nicht gesetzt ist.

Beispiele

Beschreibung lesen und setzen

// HTML: <button id="del" aria-label="Löschen">🗑️</button>
const btn = document.querySelector('#del');

console.log(btn.ariaDescription);

btn.ariaDescription = 'Entfernt den Eintrag dauerhaft. Tastenkürzel: Entf';
console.log(btn.getAttribute('aria-description'));

null Entfernt den Eintrag dauerhaft. Tastenkürzel: Entf

Dynamischer Hinweis für ein Passwortfeld

// HTML: <input id="pw" type="password" aria-label="Passwort">
const pw = document.querySelector('#pw');

const describeStrength = (value) => {
  if (value.length === 0) return null; // Attribut entfernen
  if (value.length < 8) return 'Schwach: mindestens 8 Zeichen verwenden';
  return 'Stark genug';
};

pw.addEventListener('input', () => {
  pw.ariaDescription = describeStrength(pw.value);
});

Attribut entfernen und Unterstützung prüfen

const el = document.createElement('div');

if ('ariaDescription' in Element.prototype) {
  el.ariaDescription = 'Vorschau-Kachel';
  el.ariaDescription = null; // entfernt das Attribut
  console.log(el.hasAttribute('aria-description'));
} else {
  // Fallback für ältere Browser
  el.setAttribute('aria-description', 'Vorschau-Kachel');
}

false

// Wichtig · Fallstricke

Status der Spezifikation: aria-description ist Teil von WAI-ARIA 1.3 und steht noch im Entwurf. Nicht jede Kombination aus Browser und Screenreader liest die Beschreibung zuverlässig vor. Für wichtige Informationen ist aria-describedby mit sichtbarem Text robuster.
Browser-Kompatibilität: Die Reflection-Eigenschaft gibt es in Chromium ab 112, in Safari ab 17 und in Firefox ab 119. Ältere Browser brauchen als Fallback setAttribute('aria-description', …).
Vorrang: Ist zusätzlich aria-describedby gesetzt und verweist es auf gültige Elemente, hat es Vorrang vor aria-description.
Nur Text, kein HTML: Markup im Wert wird nicht ausgewertet, sondern als reiner Text vorgelesen. Deshalb gibt es hier kein XSS-Risiko.
Kurz halten. Lange Beschreibungen, die sich bei jeder Fokussierung wiederholen, stören Screenreader-Nutzer. Die Beschreibung ersetzt keinen zugänglichen Namen (aria-label).
Leere Zeichenkette und null sind nicht dasselbe: '' lässt das Attribut leer bestehen, null entfernt es.

Siehe auch

Element.ariaLabel Element.ariaDescribedByElements Element.ariaRoleDescription Element.setAttribute() ElementInternals ContactAddress.region Element.activeViewTransition