Element.ariaLive — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaLive

Beschreibung

Die Eigenschaft ariaLive der Schnittstelle Element ist eine sogenannte ARIA-Reflexion: Sie liest und schreibt direkt das HTML-Attribut aria-live. Damit markierst du ein Element als Live-Region. Screenreader sagen dann Änderungen an seinem Inhalt an, ohne dass der Fokus dorthin wandern muss.

Typische Anwendungsfälle sind Statusmeldungen („Gespeichert“), Validierungsfehler in Formularen, Warenkorb-Zähler, Chat-Nachrichten oder Fortschrittsanzeigen, also alles, was sich dynamisch per JavaScript ändert und dem Nutzer mitgeteilt werden soll.

Erlaubt sind drei Werte:

"off": Änderungen werden nicht angesagt (Standardverhalten ohne Attribut).
"polite": Die Ansage erfolgt, sobald der Screenreader nichts anderes mehr vorliest. Das ist für die meisten Meldungen die richtige Wahl.
"assertive": Die Ansage unterbricht die aktuelle Ausgabe sofort. Nur für dringende Meldungen wie Fehler oder Zeitablauf verwenden.

Ist das Attribut nicht gesetzt, liefert die Eigenschaft null. Wenn du null zuweist, wird das Attribut entfernt. Die Eigenschaft ist gleichwertig mit setAttribute("aria-live", …), lässt sich aber kürzer und besser lesbar schreiben.

Parameter

Name	Typ	Default	Beschreibung
$wert	"off" \| "polite" \| "assertive" \| null	null	Beim Zuweisen der neue Wert für `aria-live`. Mit `null` wird das Attribut entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-live als String, oder null, wenn das Attribut fehlt. Der Wert wird nicht geprüft oder normalisiert: Ein ungültiger Wert wie "laut" kommt unverändert zurück.

Beispiele

Wert auslesen und setzen

// <div id="status" aria-live="polite"></div>
const status = document.getElementById('status');
console.log(status.ariaLive);

status.ariaLive = 'assertive';
console.log(status.getAttribute('aria-live'));

polite assertive

Statusmeldung nach dem Speichern ansagen

const meldung = document.createElement('div');
meldung.ariaLive = 'polite';
meldung.className = 'visually-hidden';
document.body.append(meldung); // Region muss VOR der Änderung existieren

const speichern = async (daten) => {
  try {
    await fetch('/api/speichern', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(daten)
    });
    meldung.textContent = 'Änderungen gespeichert.';
  } catch {
    meldung.ariaLive = 'assertive'; // Fehler sofort ansagen
    meldung.textContent = 'Speichern fehlgeschlagen. Bitte erneut versuchen.';
  }
};

speichern({ name: 'Anna' });

Live-Region vorübergehend stummschalten

const ticker = document.querySelector('#boersenticker');

const ansagenUmschalten = (aktiv) => {
  ticker.ariaLive = aktiv ? 'polite' : 'off';
};

ansagenUmschalten(false);
console.log(ticker.ariaLive);

// Attribut vollständig entfernen
ticker.ariaLive = null;
console.log(ticker.hasAttribute('aria-live'));

off false

// Wichtig · Fallstricke

Region zuerst anlegen: Viele Screenreader erkennen eine Live-Region nur, wenn sie schon im DOM steht, bevor sich ihr Inhalt ändert. Wird ein Element gleichzeitig mit aria-live und Text eingefügt, bleibt die Ansage oft aus. Deshalb die leere Region früh anlegen und erst später befüllen.
Kein display: none: Versteckte Regionen (display: none, hidden) werden nicht angesagt. Für unsichtbare Meldungen eine „visually-hidden“-CSS-Klasse verwenden.
assertive sparsam einsetzen: Der Wert unterbricht den Nutzer. Wird er zu oft verwendet, wird die Seite schwer bedienbar.
Implizite Rollen: role="status" bringt bereits polite mit, role="alert" bereits assertive. ariaLive gibt diese impliziten Werte jedoch nicht zurück, sondern nur das explizite Attribut.
Keine Prüfung: Ungültige Werte werden ohne Fehler übernommen. Assistive Technologien behandeln sie dann meist wie off.
Kompatibilität: Firefox unterstützt ARIA-Reflexion erst ab Version 119. Für ältere Browser setAttribute('aria-live', …) verwenden. Das Verhalten der Ansagen unterscheidet sich außerdem je nach Screenreader (NVDA, JAWS, VoiceOver), deshalb mit echten Screenreadern testen.

Siehe auch

Element.role Element.ariaHidden Element.ariaLevel Element.ariaLabel Element.ariaBusy