Element.ariaChecked — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaChecked

Beschreibung

Die Eigenschaft ariaChecked gehört zur ARIA-Reflexion des Element-Interfaces und spiegelt das Inhaltsattribut aria-checked direkt wider. Wenn du die Eigenschaft liest, bekommst du den Attributwert als String. Wenn du sie setzt, wird das Attribut im DOM aktualisiert. Du erreichst also dasselbe wie mit getAttribute("aria-checked") und setAttribute("aria-checked", …), nur kürzer.

Sinnvoll ist aria-checked bei selbst gebauten Bedienelementen mit den Rollen checkbox, radio, switch, menuitemcheckbox oder menuitemradio. Screenreader lesen den Zustand dann als „aktiviert“, „nicht aktiviert“ oder „teilweise aktiviert“ vor.

Gültige Werte sind:

"true": Das Element ist ausgewählt.
"false": Das Element ist auswählbar, aber gerade nicht ausgewählt.
"mixed": Gemischter bzw. unbestimmter Zustand, nur bei checkbox und menuitemcheckbox erlaubt (z. B. „Alle auswählen“, wenn nur ein Teil ausgewählt ist).
"undefined": Das Element kann nicht ausgewählt werden.

Bei nativen <input type="checkbox">- und <input type="radio">-Elementen solltest du aria-checked nicht verwenden. Dort gelten checked und indeterminate.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null		Beim Setzen: `"true"`, `"false"`, `"mixed"` oder `"undefined"`. Mit `null` wird das Attribut entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-checked als String, oder null, wenn das Attribut fehlt.

Beispiele

Zustand lesen und setzen

// <div id="agb" role="checkbox" aria-checked="false" tabindex="0">AGB akzeptieren</div>
const box = document.getElementById('agb');

console.log(box.ariaChecked);
box.ariaChecked = 'true';
console.log(box.getAttribute('aria-checked'));

false true

Eigene Checkbox per Klick und Tastatur umschalten

const toggle = (el) => {
  el.ariaChecked = el.ariaChecked === 'true' ? 'false' : 'true';
};

document.querySelectorAll('[role="checkbox"]').forEach((el) => {
  el.addEventListener('click', () => toggle(el));
  el.addEventListener('keydown', (e) => {
    if (e.key === ' ') {
      e.preventDefault(); // kein Scrollen der Seite
      toggle(el);
    }
  });
});

„Alle auswählen“ mit gemischtem Zustand

const master = document.querySelector('#alle');
const items = [...document.querySelectorAll('.eintrag[role="checkbox"]')];

const updateMaster = () => {
  const checked = items.filter((i) => i.ariaChecked === 'true').length;
  master.ariaChecked =
    checked === 0 ? 'false' : checked === items.length ? 'true' : 'mixed';
  console.log(`Master: ${master.ariaChecked}`);
};

items.forEach((i) => i.addEventListener('click', () => {
  i.ariaChecked = i.ariaChecked === 'true' ? 'false' : 'true';
  updateMaster();
}));

Master: mixed

Fallback ohne ARIA-Reflexion

const setChecked = (el, value) => {
  if ('ariaChecked' in el) {
    el.ariaChecked = value;
  } else {
    el.setAttribute('aria-checked', value);
  }
};

setChecked(document.querySelector('#newsletter'), 'true');

// Wichtig · Fallstricke

Nur Strings: Setzt du el.ariaChecked = true, wird der Wert in den String "true" umgewandelt. Deshalb immer mit Strings vergleichen, etwa el.ariaChecked === 'true'. if (el.ariaChecked) ist falsch, weil auch "false" truthy ist.
Kein Verhalten: ARIA ändert nur die Bedeutung für Hilfstechnologien. Klick- und Tastaturbedienung (Leertaste), Fokussierbarkeit (tabindex="0") und die optische Darstellung musst du selbst umsetzen.
Native Elemente bevorzugen: Nach der ersten ARIA-Regel ist ein natives <input type="checkbox"> fast immer die bessere Wahl. Bei nativen Eingabefeldern kann aria-checked zu widersprüchlichen Angaben führen.
"mixed" ist bei radio und switch nicht erlaubt. Browser behandeln den Wert dort in der Regel wie "false".
Kompatibilität: Chromium und Safari unterstützen die Eigenschaft schon länger, Firefox erst ab Version 119. Für ältere Browser setAttribute als Fallback nutzen.
CSS: Mit dem Selektor [aria-checked="true"] kannst du Zustand und Darstellung aneinander koppeln.

Siehe auch

Element.role Element.ariaPressed Element.ariaSelected Element.ariaHidden Element.ariaLevel