ElementInternals.ariaModal — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaModal

Beschreibung

Die Eigenschaft ariaModal des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-modal. Damit kann ein Custom Element (Web Component) festlegen, ob es für assistive Technologien wie Screenreader als modal gilt. Ein Element mit dem Wert "true" bedeutet: Inhalte außerhalb des Elements sind gerade nicht bedienbar, und der Screenreader soll sich auf den Inhalt des Dialogs beschränken.

Im Unterschied zu Element.ariaModal bzw. dem sichtbaren HTML-Attribut aria-modal setzt ElementInternals.ariaModal einen Standardwert (die Default-Semantik) der Komponente, ohne im DOM ein Attribut zu hinterlassen. Verwendende der Komponente können diesen Wert mit einem eigenen aria-modal-Attribut am Host-Element überschreiben. Das hält das Markup schlank und kapselt das Verhalten der Barrierefreiheit in der Komponente.

Sinnvoll ist ariaModal zusammen mit einer passenden Rolle, also internals.role = "dialog" oder "alertdialog". Den Wert setzt man meist dann, wenn der Dialog geöffnet wird, und nimmt ihn beim Schließen wieder zurück. Ein Zugriff auf ElementInternals erhält man nur über this.attachInternals() im Konstruktor eines autonomen Custom Elements.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"` (Element ist modal), `"false"` (nicht modal, Standard laut ARIA) oder `null`, um den Standardwert zu entfernen. Andere Werte werden als Zeichenkette gespeichert, gelten laut ARIA aber als `"false"`.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Standardwert als Zeichenkette ("true" oder "false") oder null, wenn kein Wert gesetzt ist. Ein aria-modal-Attribut am Host-Element wird hier nicht zurückgegeben.

Beispiele

Modaler Dialog als Custom Element

class MyDialog extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Standard-Semantik: Dialog, zunächst nicht modal
    this.#internals.role = 'dialog';
    this.#internals.ariaModal = 'false';
  }

  open() {
    this.hidden = false;
    this.#internals.ariaModal = 'true';
    this.focus();
  }

  close() {
    this.hidden = true;
    this.#internals.ariaModal = 'false';
  }

  get internals() {
    return this.#internals;
  }
}

customElements.define('my-dialog', MyDialog);

const dlg = document.createElement('my-dialog');
dlg.tabIndex = -1;
document.body.append(dlg);
dlg.open();
console.log(dlg.internals.ariaModal);
dlg.close();
console.log(dlg.internals.ariaModal);

true false

Standardwert gegenüber dem HTML-Attribut

class AlertBox extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'alertdialog';
    this.internals.ariaModal = 'true';
  }
}
customElements.define('alert-box', AlertBox);

const box = document.createElement('alert-box');
document.body.append(box);

// Kein sichtbares Attribut im DOM
console.log(box.getAttribute('aria-modal'));
console.log(box.internals.ariaModal);

// Nutzer der Komponente überschreibt den Standardwert
box.setAttribute('aria-modal', 'false');
console.log(box.ariaModal);            // Attribut-Reflexion am Element
console.log(box.internals.ariaModal);  // Standardwert bleibt erhalten

null true false true

Funktionsprüfung mit Fallback

class SafeDialog extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals?.();
    if (internals && 'ariaModal' in internals) {
      internals.role = 'dialog';
      internals.ariaModal = 'true';
    } else {
      // Fallback für ältere Browser: sichtbare Attribute setzen
      this.setAttribute('role', 'dialog');
      this.setAttribute('aria-modal', 'true');
    }
  }
}
customElements.define('safe-dialog', SafeDialog);
console.log('ariaModal' in ElementInternals.prototype);

true

// Wichtig · Fallstricke

Nur Zeichenketten: Der Wert ist ein String, kein Boolean. internals.ariaModal = true wird zu "true" umgewandelt, aber false zu "false". Wer den Wert zurücksetzen will, sollte null zuweisen.
Attribut hat Vorrang: Ein aria-modal-Attribut am Host-Element überschreibt den Standardwert aus ElementInternals. Der Getter von internals.ariaModal zeigt diese Überschreibung nicht an.
Kein Fokus-Management: ariaModal ändert nur die Semantik für Hilfstechnologien. Fokus festhalten, Escape zum Schließen und das Sperren des Hintergrunds (z. B. mit inert) musst du selbst umsetzen. Alternativ bietet das native <dialog> mit showModal() das alles fertig.
Nur mit Rolle sinnvoll: aria-modal gilt nur für die Rollen dialog und alertdialog.
Unterstützung: Die Spiegelung von ARIA-Werten in ElementInternals gibt es in Chromium seit Version 90, in Safari seit 16.4 und in Firefox seit 119. attachInternals() funktioniert nur bei autonomen Custom Elements und löst sonst einen NotSupportedError aus.

Siehe auch

ElementInternals.ariaAtomic ElementInternals.ariaLabel ElementInternals.ariaLevel ElementInternals.ariaSort ElementInternals.ariaBusy