Modal-Stack: mehrere Dialoge übereinander verwalten

1. Warum ein einzelnes offen/geschlossen-Flag nicht ausreicht

Die meisten Modal-Implementierungen starten mit einem einzigen reaktiven Wert, etwa isOpen, der zwischen wahr und falsch wechselt. Für ein isoliertes Modal funktioniert das gut, doch sobald aus diesem Dialog heraus ein zweiter Dialog geöffnet wird, etwa eine Sicherheitsabfrage vor dem Löschen eines Datensatzes, entsteht ein Konflikt: Beide Modals teilen sich denselben Zustand, sodass das Schließen des zweiten Dialogs versehentlich auch den ersten schließt oder umgekehrt.

Das eigentliche Problem ist konzeptioneller Natur. Ein Boolean beschreibt einen Zustand mit genau zwei Ausprägungen, aber die tatsächliche Anforderung ist eine geordnete Menge gleichzeitig offener Dialoge mit einer klaren Reihenfolge, wer zuletzt geöffnet wurde und wer beim Drücken von Escape als Erstes wieder verschwinden soll. Diese Reihenfolge lässt sich nur mit einer Datenstruktur abbilden, die mehr kann als nur ja oder nein zu speichern, nämlich mit einem Stapel.

2. Der Store als Stack: Datenstruktur und API

Ein zentraler Alpine-Store bildet den Stack als einfaches Array ab, in dem jeder Eintrag eine eindeutige ID sowie das Element referenziert, das den Dialog ausgelöst hat. Neue Modals werden mit push ans Ende des Arrays angehängt, das oberste, also zuletzt geöffnete Modal befindet sich damit immer am Ende der Liste. Diese einfache Regel macht es trivial zu bestimmen, welches Modal gerade aktiv ist und auf welches sich globale Tastatur-Events beziehen sollen.

Die API des Stores bleibt bewusst schlank: open(id, triggerEl) legt einen neuen Eintrag an, close(id) entfernt einen bestimmten Eintrag unabhängig von seiner Position, und closeTop() entfernt gezielt nur den obersten Eintrag. Getter wie isTop(id) und depth(id) liefern den einzelnen Modal-Komponenten die Information, die sie für Z-Index und Fokus-Verhalten benötigen, ohne dass jede Komponente selbst den gesamten Stack durchsuchen muss.

// resources/js/stores/modal-stack.js
document.addEventListener('alpine:init', () => {
  Alpine.store('modalStack', {
    stack: [],

    open(id, triggerEl) {
      // Doppeltes Oeffnen desselben Modals verhindern
      if (this.stack.some((entry) => entry.id === id)) return;
      this.stack.push({ id, triggerEl });
    },

    close(id) {
      this.stack = this.stack.filter((entry) => entry.id !== id);
    },

    closeTop() {
      const top = this.stack.at(-1);
      if (top) this.close(top.id);
    },

    isTop(id) {
      return this.stack.at(-1)?.id === id;
    },

    depth(id) {
      return this.stack.findIndex((entry) => entry.id === id);
    },
  });
});

3. Die Modal-Komponente registriert sich beim Store

Jede einzelne Modal-Komponente kennt nur ihre eigene ID und meldet sich beim Öffnen und Schließen am zentralen Store an beziehungsweise ab. Wichtig ist, dass die Komponente selbst keine eigene Kopie des offen/geschlossen-Zustands führt, sondern ausschließlich aus dem Store abfragt, ob ihre ID aktuell im Stack enthalten ist. Damit gibt es genau eine Quelle der Wahrheit, unabhängig davon, wie viele Modal-Instanzen im DOM existieren.

Das x-data-Objekt einer Modal-Komponente bleibt dadurch überraschend kompakt. Es liefert lediglich berechnete Eigenschaften, die auf den Store zugreifen, sowie die beiden Methoden zum Öffnen und Schließen. Die gesamte Stack-Logik, Reihenfolge, Fokus und Z-Index, bleibt zentral im Store gekapselt und muss nicht in jeder einzelnen Modal-Instanz neu implementiert werden.

4. Praxisbeispiel: Bestätigungsdialog über Detail-Modal

Ein alltägliches Szenario im Shop-Backend: Ein Kunde öffnet ein Detail-Modal mit den Informationen einer gespeicherten Adresse und klickt dort auf Löschen. Statt die Adresse sofort zu entfernen, öffnet sich ein zweites, kleineres Bestätigungsmodal über dem ersten. Beide Dialoge bleiben im DOM erhalten, nur der Bestätigungsdialog liegt sichtbar und interaktiv über dem Detail-Modal, das im Hintergrund weiterhin sichtbar, aber durch ein Overlay leicht abgedunkelt bleibt.

Der folgende Ausschnitt zeigt, wie zwei Modal-Instanzen unabhängig voneinander denselben Store nutzen. Das Detail-Modal öffnet beim Klick auf Löschen lediglich ein weiteres Modal, ohne sich selbst zu schließen, und reagiert erst auf das vom Bestätigungsdialog ausgelöste Custom Event, wenn die Löschung tatsächlich bestätigt wurde.

<div
  x-data="{ id: 'address-detail' }"
  x-show="$store.modalStack.stack.some(e => e.id === id)"
  x-init="$store.modalStack.open(id, $refs.trigger)"
  @close-address-detail.window="$store.modalStack.close(id)"
  class="fixed inset-0 flex items-center justify-center"
  :style="`z-index: ${1000 + $store.modalStack.depth(id)}`"
>
  <div class="bg-white rounded-lg p-6 w-96">
    <h2 class="text-lg font-semibold">Adresse bearbeiten</h2>
    <button
      @click="$store.modalStack.open('confirm-delete', $event.target)"
      class="mt-4 text-red-600"
    >
      Adresse löschen
    </button>
  </div>
</div>

<div
  x-data="{ id: 'confirm-delete' }"
  x-show="$store.modalStack.stack.some(e => e.id === id)"
  class="fixed inset-0 flex items-center justify-center"
  :style="`z-index: ${1000 + $store.modalStack.depth(id)}`"
>
  <div class="bg-white rounded-lg p-6 w-80">
    <p>Adresse wirklich unwiderruflich löschen?</p>
    <button @click="$store.modalStack.close(id); $dispatch('close-address-detail')">
      Ja, löschen
    </button>
    <button @click="$store.modalStack.close(id)">Abbrechen</button>
  </div>
</div>

5. Z-Index-Berechnung basierend auf der Stack-Position

Statt für jedes Modal einen festen Z-Index-Wert in CSS zu hinterlegen, berechnet jede Instanz ihren Z-Index dynamisch aus ihrer Position im Stack. Der Store liefert über depth(id) den Index innerhalb des Arrays, und die Komponente addiert diesen Wert auf eine Basiszahl, üblicherweise deutlich über den Z-Index-Werten des restlichen Layouts, damit auch bei fünf oder sechs verschachtelten Ebenen keine Kollision mit anderen fixierten Elementen entsteht.

Dieser Ansatz erspart es, für jede neue Modal-Kombination im Stylesheet einen weiteren, höheren Z-Index-Wert zu pflegen. Das Overlay hinter jedem Modal wird auf dieselbe Weise berechnet, jeweils einen Wert niedriger als das zugehörige Modal selbst, sodass jede Ebene ihr eigenes, korrekt gestapeltes Overlay erhält, ohne dass sich Overlays mehrerer Ebenen gegenseitig überdecken.

6. Fokus-Trap pro Modal-Ebene

Ein Fokus-Trap sorgt dafür, dass die Tabulatortaste den Fokus innerhalb eines Dialogs hält, statt in Hintergrundelemente zu springen. Bei verschachtelten Modals muss dieser Trap konsequent nur für das jeweils oberste Modal aktiv sein, alle darunterliegenden Traps müssen währenddessen pausieren. Andernfalls würde die Tabulatortaste im Bestätigungsdialog unerwartet zu Elementen des dahinterliegenden Detail-Modals springen, was für Tastaturnutzer sofort verwirrend wirkt.

In der Praxis prüft jede Fokus-Trap-Instanz vor jedem Tab-Event über isTop(id), ob sie sich aktuell auf der obersten Ebene befindet. Nur in diesem Fall greift sie überhaupt ein und verhindert das Verlassen des Dialogs; auf allen anderen Ebenen lässt sie das Standardverhalten des Browsers unangetastet, weil dort ohnehin kein Element sichtbar interaktiv sein sollte, solange ein weiteres Modal darüber liegt.

7. Fokus-Rückgabe beim Schließen des obersten Modals

Barrierefreiheit endet nicht beim Öffnen eines Dialogs, sondern schließt die korrekte Rückgabe des Fokus beim Schließen mit ein. Wird ein Modal geschlossen, muss der Fokus exakt zu dem Element zurückkehren, das den Dialog ursprünglich ausgelöst hat, nicht einfach zum body-Element oder zum nächsten fokussierbaren Element im DOM. Genau dafür speichert der Store bei jedem open-Aufruf eine Referenz auf das auslösende Element mit.

Beim Schließen ruft der Store triggerEl.focus() für den entfernten Eintrag auf, direkt bevor das entsprechende Modal aus dem Array entfernt wird. Bei einem Modal-Stack ist dabei besonders wichtig, dass sich der Fokus jeweils nur um genau eine Ebene zurückbewegt: Schließt der Nutzer den Bestätigungsdialog, landet der Fokus auf dem Löschen-Button im Detail-Modal, nicht etwa direkt auf dem Element, das ursprünglich das Detail-Modal geöffnet hatte.

8. Escape-Taste nur für das oberste Modal behandeln

Ein einzelner globaler Escape-Listener auf window genügt für den gesamten Stack, sofern er konsequent immer nur den obersten Eintrag entfernt. Die naheliegende, aber falsche Implementierung wäre ein eigener Escape-Listener pro Modal-Komponente, denn dann würde ein einzelner Tastendruck alle offenen Modals gleichzeitig schließen, weil jeder Listener unabhängig voneinander auf dasselbe Event reagiert.

Richtig gelöst reicht ein zentraler Listener im Store selbst, der bei jedem Escape-Event schlicht closeTop() aufruft. Da diese Methode ohnehin immer nur den letzten Eintrag des Arrays entfernt, verhält sich das System automatisch korrekt: Ein Tastendruck schließt genau eine Ebene, mehrfaches Drücken arbeitet den Stack von oben nach unten ab, bis kein Modal mehr geöffnet ist.

9. Body-Scroll-Lock nur einmal setzen, mit Referenzzählung

Ein häufiger Fehler bei mehreren gleichzeitig offenen Modals besteht darin, dass jede Instanz beim Öffnen unabhängig overflow: hidden auf dem body-Element setzt und beim eigenen Schließen wieder entfernt. Schließt der Nutzer zuerst den Bestätigungsdialog, entfernt dessen Komponente die Sperre, obwohl das Detail-Modal weiterhin offen ist, und der Hintergrund lässt sich plötzlich wieder scrollen, während sichtbar noch ein Dialog aktiv ist.

Die saubere Lösung liegt auch hier im Store: Er zählt lediglich die Länge des Stack-Arrays. Sobald der erste Eintrag hinzukommt, setzt der Store die Scroll-Sperre einmalig, und erst wenn der Stack wieder vollständig leer ist, entfernt er sie. Einzelne Modal-Komponenten müssen sich um Scroll-Verhalten dadurch überhaupt nicht mehr kümmern, weil diese Verantwortung vollständig zentralisiert im Store liegt.

10. Zusammenfassung

11. FAQ: Modal-Stack in Alpine.js: Das Wichtigste auf einen Blick