Element.ariaExpanded — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaExpanded

Beschreibung

Die Eigenschaft ariaExpanded gehört zur ARIA-Reflexion (ARIAMixin) der Element-Schnittstelle. Sie liest und schreibt direkt das Attribut aria-expanded. Du musst dafür also nicht mehr getAttribute() oder setAttribute() aufrufen. Screenreader und andere Hilfstechnologien erfahren über das Attribut, ob ein zugehöriger Bereich gerade sichtbar (aufgeklappt) oder verborgen (zugeklappt) ist.

Typische Einsatzfälle sind Schalter für Akkordeons, Dropdown-Menüs, Navigations-Menüs auf Mobilgeräten („Hamburger-Menü“), Baumansichten (role="treeitem") und Kombinationsfelder (role="combobox"). Das Attribut gehört auf das steuernde Element, zum Beispiel den <button>, und nicht auf den auf- und zuklappbaren Bereich selbst.

Der Wert ist immer ein String oder null:

"true": Der gesteuerte Bereich ist aufgeklappt.
"false": Der gesteuerte Bereich ist zugeklappt.
"undefined" bzw. null (Attribut fehlt): Das Element lässt sich nicht auf- und zuklappen.

Wenn du null zuweist, wird das Attribut entfernt.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	string \| null		Neuer Wert für `aria-expanded`: `"true"`, `"false"` oder `"undefined"`. Mit `null` wird das Attribut entfernt. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-expanded als String ("true", "false", "undefined") oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Wert lesen und setzen

// HTML: <button id="menu-btn" aria-expanded="false" aria-controls="menu">Menü</button>
const btn = document.querySelector('#menu-btn');

console.log(btn.ariaExpanded);        // aktueller Wert
btn.ariaExpanded = 'true';
console.log(btn.getAttribute('aria-expanded'));

false true

Barrierefreies Akkordeon umschalten

// HTML:
// <button class="accordion" aria-expanded="false" aria-controls="panel-1">Details</button>
// <div id="panel-1" hidden>Inhalt …</div>
document.querySelectorAll('.accordion').forEach((button) => {
  button.addEventListener('click', () => {
    const isOpen = button.ariaExpanded === 'true'; // String-Vergleich!
    const panel = document.getElementById(button.getAttribute('aria-controls'));

    button.ariaExpanded = String(!isOpen);
    panel.hidden = isOpen;
  });
});

Dropdown mit Escape-Taste schließen

const toggle = document.querySelector('#nav-toggle');
const nav = document.querySelector('#main-nav');

const setOpen = (open) => {
  toggle.ariaExpanded = open ? 'true' : 'false';
  nav.hidden = !open;
};

toggle.addEventListener('click', () => setOpen(toggle.ariaExpanded !== 'true'));

document.addEventListener('keydown', (event) => {
  if (event.key === 'Escape' && toggle.ariaExpanded === 'true') {
    setOpen(false);
    toggle.focus(); // Fokus zurück auf den Schalter
  }
});

Attribut entfernen

const item = document.querySelector('#static-item');
item.ariaExpanded = null; // entfernt aria-expanded komplett
console.log(item.hasAttribute('aria-expanded'), item.ariaExpanded);

false null

// Wichtig · Fallstricke

String statt Boolean: Der Wert ist immer ein String. if (el.ariaExpanded) ist auch bei "false" wahr, weil jeder nicht leere String als wahr gilt. Vergleiche deshalb immer mit === 'true'.
Keine automatische Sichtbarkeit: ariaExpanded ändert nur die Semantik für Hilfstechnologien. Das Ein- und Ausblenden des Bereichs (etwa über hidden oder CSS) musst du selbst synchron halten.
Richtiges Element: Setze das Attribut auf das steuernde Element (Button, Combobox, Treeitem), nicht auf den Bereich selbst. Ergänze am besten aria-controls.
Natives HTML bevorzugen: <details>/<summary> liefern den Auf- und Zu-Zustand ohne zusätzliches ARIA.
Kompatibilität: Chromium und Safari unterstützen die Eigenschaft schon länger, Firefox erst ab Version 119. Für ältere Browser setAttribute('aria-expanded', …) verwenden. Das funktioniert überall.

Siehe auch

Element.ariaDisabled Element.ariaColIndex Element.ariaRowIndex Element.ariaChecked Element.ariaHidden