Element.ariaDisabled — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaDisabled

Beschreibung

Die Eigenschaft ariaDisabled gehört zum ARIA-Reflection-Mechanismus des Element-Interfaces. Sie spiegelt das HTML-Attribut aria-disabled: Liest man die Eigenschaft, erhält man den aktuellen Attributwert. Setzt man sie, wird das Attribut im DOM geändert. Weist man null zu, wird das Attribut entfernt.

Mit aria-disabled="true" teilt man Screenreadern und anderen assistiven Technologien mit, dass ein Element zwar sichtbar und wahrnehmbar, aber nicht bedienbar ist. Das native disabled-Attribut entfernt ein Element aus der Tab-Reihenfolge. aria-disabled tut das nicht: Das Element bleibt fokussierbar und löst weiterhin Klick- und Tastatur-Ereignisse aus. Genau das ist oft gewollt, etwa wenn Nutzer einen deaktivierten Button per Tastatur erreichen sollen, um einen Tooltip mit dem Grund der Deaktivierung zu lesen.

Typische Anwendungsfälle sind eigene Steuerelemente auf Basis von <div role="button">, Menüpunkte, Tabs oder Listbox-Optionen, bei denen es kein natives disabled gibt. Das Verhalten selbst, also das Unterdrücken der Aktion, muss man in JavaScript umsetzen. ARIA ändert nur die Semantik, nie das Verhalten.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"` (Element und alle fokussierbaren Nachfahren sind deaktiviert) oder `"false"` (nicht deaktiviert). Mit `null` wird das Attribut entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des aria-disabled-Attributs als String ("true" oder "false"). Ist das Attribut nicht gesetzt, ist der Wert null.

Beispiele

Attributwert lesen und setzen

// HTML: <div id="save" role="button" tabindex="0" aria-disabled="true">Speichern</div>
const btn = document.getElementById('save');

console.log(btn.ariaDisabled);                       // aktueller Wert
btn.ariaDisabled = 'false';
console.log(btn.getAttribute('aria-disabled'));      // Attribut wurde gespiegelt
btn.ariaDisabled = null;
console.log(btn.hasAttribute('aria-disabled'));      // Attribut entfernt

true false false

Eigener Button: Aktion blockieren, Fokus behalten

const btn = document.querySelector('#submit');

const setDisabled = (el, disabled) => {
  el.ariaDisabled = disabled ? 'true' : 'false';
  el.classList.toggle('is-disabled', disabled);
};

const handleActivate = (event) => {
  // Semantik allein blockiert nichts, deshalb selbst prüfen
  if (btn.ariaDisabled === 'true') {
    event.preventDefault();
    return;
  }
  console.log('Formular wird gesendet');
};

btn.addEventListener('click', handleActivate);
btn.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') handleActivate(e);
});

setDisabled(btn, true);

Absenden-Button abhängig von der Formularvalidität

const form = document.querySelector('form');
const submit = form.querySelector('button[type="submit"]');

const update = () => {
  submit.ariaDisabled = String(!form.checkValidity());
};

form.addEventListener('input', update);
form.addEventListener('submit', (e) => {
  if (submit.ariaDisabled === 'true') {
    e.preventDefault();
    form.reportValidity(); // zeigt, welche Felder fehlen
  }
});
update();

// Wichtig · Fallstricke

Es ist ein String, kein Boolean: el.ariaDisabled = false setzt das Attribut auf "false". Eine Prüfung wie if (el.ariaDisabled) ist auch bei "false" wahr, weil nicht-leere Strings truthy sind. Deshalb immer explizit mit === 'true' vergleichen.
Kein Verhalten: aria-disabled blockiert weder Klicks noch Formularabsendungen noch Fokus. Das musst du selbst in JavaScript umsetzen. Bei nativen Elementen wie <button> oder <input> ist oft das native disabled die bessere Wahl. Wenn das Element fokussierbar bleiben soll, ist aria-disabled genau richtig.
Nicht beide gleichzeitig nötig: Wer disabled setzt, braucht kein zusätzliches aria-disabled. Die Deaktivierung wird dann automatisch an den Accessibility-Tree gemeldet.
Vererbung: aria-disabled="true" gilt semantisch auch für alle fokussierbaren Nachfahren.
Styling: Die Pseudoklasse :disabled greift nicht. Stattdessen den Attributselektor [aria-disabled="true"] verwenden.
Kompatibilität: Firefox unterstützt ARIA-Reflection erst ab Version 119. Für ältere Browser setAttribute('aria-disabled', 'true') nutzen. Das funktioniert überall.

Siehe auch

Element.role Element.ariaInvalid Element.ariaExpanded Element.ariaLabel Element.ariaChecked