Element.ariaModal — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaModal

Beschreibung

Die Eigenschaft ariaModal gehört zur ARIA-Reflexion (ARIAMixin) des Element-Interfaces. Sie spiegelt das HTML-Attribut aria-modal direkt wider: Wer die Eigenschaft setzt, ändert das Attribut und umgekehrt. Damit lässt sich der Zustand ohne setAttribute()/getAttribute() bearbeiten.

aria-modal="true" teilt Hilfstechnologien wie Screenreadern mit, dass Inhalte außerhalb des Elements gerade nicht erreichbar sind. Der Screenreader beschränkt die virtuelle Navigation dann auf den Dialog. Üblich ist das bei Elementen mit role="dialog" oder role="alertdialog", die Sie selbst gebaut haben.

Wichtig: Das Attribut ändert nur die semantische Auszeichnung. Es macht den Hintergrund nicht tatsächlich unbedienbar. Um den Fokus im Dialog zu halten, den Hintergrund zu sperren (z. B. mit inert) und den Dialog mit Escape zu schließen, müssen Sie selbst sorgen. Das native <dialog>-Element mit showModal() erledigt das alles automatisch und braucht kein aria-modal.

Rückgabewert

Typ

string | null

Beschreibung

Ein String mit "true" (Element ist modal) oder "false" (Standard, nicht modal). null, wenn das Attribut aria-modal nicht gesetzt ist. Wenn Sie null zuweisen, wird das Attribut entfernt.

Beispiele

Wert lesen und setzen

// HTML: <div id="dlg" role="dialog" aria-modal="true" aria-labelledby="dlg-title">…</div>
const dlg = document.getElementById('dlg');

console.log(dlg.ariaModal);            // "true"

dlg.ariaModal = 'false';
console.log(dlg.getAttribute('aria-modal')); // "false"

dlg.ariaModal = null;                  // entfernt das Attribut
console.log(dlg.hasAttribute('aria-modal'));  // false

true false false

Selbst gebauten Modal-Dialog öffnen und schließen

const dialog = document.querySelector('#login-dialog');
const main = document.querySelector('main');
let lastFocus = null;

const openDialog = () => {
  lastFocus = document.activeElement;
  dialog.hidden = false;
  dialog.ariaModal = 'true';   // Semantik für Screenreader
  main.inert = true;           // Hintergrund wirklich sperren
  dialog.querySelector('input')?.focus();
};

const closeDialog = () => {
  dialog.hidden = true;
  dialog.ariaModal = null;
  main.inert = false;
  lastFocus?.focus();          // Fokus zurückgeben
};

dialog.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') closeDialog();
});

document.querySelector('#open-login').addEventListener('click', openDialog);

Fallback für Browser ohne ARIA-Reflexion

const setModal = (el, isModal) => {
  const value = isModal ? 'true' : 'false';
  if ('ariaModal' in Element.prototype) {
    el.ariaModal = value;
  } else {
    el.setAttribute('aria-modal', value);
  }
};

const panel = document.querySelector('[role="dialog"]');
setModal(panel, true);
console.log(panel.getAttribute('aria-modal'));

true

// Wichtig · Fallstricke

String statt Boolean: Der Wert ist immer ein String. if (el.ariaModal) ist auch bei "false" wahr, weil jeder nicht leere String als wahr gilt. Vergleichen Sie deshalb ausdrücklich mit === 'true'. Wenn Sie false als Boolean zuweisen, wird daraus der String "false".
Keine Verhaltensänderung: aria-modal sperrt weder den Fokus noch den Hintergrund. Nutzen Sie dafür zusätzlich inert, eine Fokusfalle und die Escape-Taste – oder gleich <dialog> mit showModal().
Setzen Sie aria-modal="true" nur, solange der Dialog sichtbar ist. Sonst können Screenreader den übrigen Seiteninhalt fälschlich ausblenden.
Sinnvoll ist das Attribut nur zusammen mit role="dialog" oder role="alertdialog" und einem zugänglichen Namen (aria-labelledby/aria-label).
Kompatibilität: Firefox unterstützt die ARIA-Reflexions-Eigenschaften erst ab Version 119. Für ältere Browser verwenden Sie setAttribute('aria-modal', …).

Siehe auch

Element.role Element.ariaReadOnly Element.ariaLabel Element.ariaLevel Element.ariaSort