Mini Cart Vorschau mit Alpine.js in Hyvä bauen

1. Warum eine Mini Cart Vorschau den Unterschied macht

Eine Mini Cart Vorschau ist der kleine Flyout, der beim Klick oder Hover auf das Warenkorb-Icon erscheint und die zuletzt hinzugefügten Artikel, die Zwischensumme und einen Checkout-Link zeigt. Ohne diese Vorschau muss der Kunde nach jedem Add-to-Cart-Klick entweder auf die volle Warenkorbseite wechseln oder blind weiter einkaufen, ohne zu wissen, ob der Artikel wirklich im Warenkorb gelandet ist. Gerade in Magento-Shops mit Hyvä Theme, wo bewusst auf schwere JavaScript-Frameworks verzichtet wird, ist eine leichte, reaktive Mini Cart ein direkter Hebel für Conversion und wahrgenommene Geschwindigkeit.

Klassische Luma-Themes lösten dieses Problem über Knockout.js und die Customer-Data-Section-Mechanik von Magento, die bei jedem Seitenaufruf mehrere Sections nachlädt, unabhängig davon, ob sie gebraucht werden. In Hyvä übernimmt Alpine.js diese Aufgabe deutlich schlanker: Die Mini Cart Vorschau wird als eigenständige x-data-Komponente definiert, reagiert auf ein einziges Custom Event nach dem Add-to-Cart-Request und lädt nur die tatsächlich benötigten Cart-Daten nach. Das Ergebnis ist ein Flyout, der sich anfühlt wie eine Single-Page-Application, ohne dass eine komplette SPA-Architektur nötig wäre.

In den folgenden Abschnitten entsteht eine vollständige Mini Cart-Komponente Schritt für Schritt: vom State-Design über das Nachladen der Cart-Daten bis zur Mengenänderung direkt im Flyout und der barrierefreien Fokus-Steuerung. Jeder Codeblock ist so geschrieben, dass er sich direkt in ein Hyvä-Layout-Handle wie default.xml oder ein eigenes minicart.phtml übernehmen lässt.

2. Grundgerüst: x-data State für den Warenkorb

Der Ausgangspunkt jeder Mini Cart Vorschau ist ein sauber strukturierter State. Statt einzelner loser Variablen bündelt man Artikel, Anzahl, Zwischensumme und Ladezustand in einem Objekt, das über x-data registriert wird. Wichtig ist, dass dieses Objekt als benannte Alpine-Komponente definiert wird, damit es aus mehreren Stellen im DOM angesprochen werden kann, etwa vom Header-Icon und vom Flyout-Panel gleichzeitig.

Für global geteilten Zustand über mehrere Komponenten hinweg ist Alpine.store() die richtige Wahl. Das Cart-Icon im Header und das Flyout-Panel im Footer-Bereich des Headers müssen denselben Warenkorb-Stand kennen, ohne dass Daten mühsam zwischen Komponenten weitergereicht werden. Ein globaler Store macht die Mini Cart zu einer einzigen Quelle der Wahrheit, die von jeder Komponente auf der Seite gelesen werden kann.

// Global Alpine store for the mini cart state
document.addEventListener('alpine:init', () => {
  Alpine.store('miniCart', {
    items: [],
    itemCount: 0,
    subtotal: '0,00 €',
    isOpen: false,
    isLoading: false,

    // Toggle the flyout panel open/closed
    toggle() {
      this.isOpen = !this.isOpen;
      if (this.isOpen) {
        this.refresh();
      }
    },

    close() {
      this.isOpen = false;
    },

    // Replace the whole cart state after a fetch
    setData(data) {
      this.items = data.items;
      this.itemCount = data.itemCount;
      this.subtotal = data.subtotal;
      this.isLoading = false;
    }
  });
});

Diese Struktur trennt bewusst Darstellung und Zustand. Die Mini Cart-Komponente im Markup ruft nur noch $store.miniCart.toggle() oder $store.miniCart.items auf, ohne selbst Fetch-Logik oder Berechnungen zu enthalten. Das erleichtert Tests und macht den Store austauschbar, falls später zusätzliche Kanäle wie ein Sticky-Add-to-Cart-Button denselben Zustand lesen sollen.

3. Cart-Daten laden: Section Data und GraphQL kombinieren

Magento hält Warenkorb-Daten serverseitig in Sections, die über den Endpunkt customer/section/load abgerufen werden, oder alternativ über eine GraphQL-Query gegen den cart-Typ. Für eine performante Mini Cart Vorschau in Hyvä ist GraphQL meist die sauberere Wahl, weil sich die Query exakt auf die Felder beschränken lässt, die der Flyout wirklich braucht: Artikelnamen, Bild, Menge, Zeilenpreis und Gesamtsumme.

Der Trick liegt darin, den Refresh-Aufruf nicht bei jedem Seitenaufruf auszuführen, sondern gezielt dann, wenn sich der Warenkorb tatsächlich geändert hat. Das reduziert unnötige Requests und hält die Mini Cart trotzdem stets aktuell, sobald der Kunde sie öffnet oder ein Add-to-Cart-Event eintrifft.

Alpine.store('miniCart').refresh = async function () {
  this.isLoading = true;

  const query = `
    query MiniCart($cartId: String!) {
      cart(cart_id: $cartId) {
        total_quantity
        items { id quantity product { name thumbnail { url } } prices { row_total { value } } }
        prices { grand_total { value currency } }
      }
    }
  `;

  const cartId = window.localStorage.getItem('mage-cart-id');
  const response = await fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables: { cartId } })
  });

  const { data } = await response.json();
  this.setData({
    items: data.cart.items,
    itemCount: data.cart.total_quantity,
    subtotal: new Intl.NumberFormat('de-DE', { style: 'currency', currency: data.cart.prices.grand_total.currency })
      .format(data.cart.prices.grand_total.value)
  });
};

Wer bereits mit Hyvä-GraphQL-Endpoints für den Checkout arbeitet, kann dieselbe Query-Struktur wiederverwenden und muss keine zweite REST-Schnittstelle pflegen. Die Mini Cart Vorschau profitiert davon, dass GraphQL nur genau die angeforderten Felder zurückgibt, was besonders bei vielen gleichzeitigen Kunden Server-Last spart.

4. Add-to-Cart-Event abfangen und Icon aktualisieren

Damit die Mini Cart nach einem Add-to-Cart-Klick automatisch aktualisiert wird, muss das Add-to-Cart-Formular ein Custom Event auslösen, sobald die Antwort vom Server eintrifft. In Hyvä geschieht das typischerweise über window.dispatchEvent() direkt im Formular-Handler, nachdem der Fetch-Request erfolgreich war. Das Icon im Header lauscht auf genau dieses Event und ruft den Store-Refresh auf.

Diese Entkopplung über Events ist ein zentrales Alpine.js-Pattern: Die Formular-Komponente kennt die Mini Cart nicht direkt, sondern kommuniziert nur über ein Event, auf das beliebig viele andere Komponenten reagieren können, etwa auch ein Sticky-Add-to-Cart-Balken oder eine Erfolgsbenachrichtigung.

// Add-to-cart form component
function addToCartForm() {
  return {
    isSubmitting: false,

    async submit(event) {
      event.preventDefault();
      this.isSubmitting = true;

      const formData = new FormData(event.target);
      const response = await fetch(event.target.action, { method: 'POST', body: formData });

      this.isSubmitting = false;

      if (response.ok) {
        // Notify every component listening for cart changes
        window.dispatchEvent(new CustomEvent('cart-updated', {
          detail: { quantity: formData.get('qty') }
        }));
      }
    }
  };
}

// Header icon listens globally, independent of where the form lives
document.addEventListener('cart-updated', () => {
  Alpine.store('miniCart').refresh();
  Alpine.store('miniCart').isOpen = true;
});

Ein häufiger Fehler an dieser Stelle: Entwickler rufen den Refresh direkt aus der Formular-Komponente auf, statt über ein globales Event zu gehen. Das funktioniert zunächst, bricht aber, sobald ein zweites Formular auf derselben Seite existiert, etwa in einer Produktliste mit mehreren Add-to-Cart-Buttons. Das Event-Pattern hält die Mini Cart Vorschau unabhängig von der Anzahl und Position der Formulare auf der Seite.

5. Flyout-Positionierung und Transitions

Der visuelle Teil der Mini Cart ist ein absolut positioniertes Panel, das mit x-show und x-transition ein- und ausgeblendet wird. Wichtig ist, das Panel nicht abrupt erscheinen zu lassen, sondern mit einer kurzen Transition, die dem Kunden signalisiert, dass hier gerade etwas passiert ist, ohne aufdringlich zu wirken.

x-anchor aus dem offiziellen Alpine-Anchor-Plugin ist eine elegante Lösung, um das Flyout-Panel automatisch relativ zum Cart-Icon zu positionieren, auch wenn sich die Icon-Position durch responsive Breakpoints verschiebt. Ohne dieses Plugin reicht in den meisten Layouts aber auch simples absolute right-0 auf einem relative-Container aus.

<div x-data class="relative">
  <button
    @click="$store.miniCart.toggle()"
    class="relative p-2"
    aria-haspopup="true"
    :aria-expanded="$store.miniCart.isOpen"
  >
    <span class="sr-only">Warenkorb öffnen</span>
    <svg class="w-6 h-6" aria-hidden="true"><!-- cart icon --></svg>
    <span
      x-show="$store.miniCart.itemCount > 0"
      x-text="$store.miniCart.itemCount"
      class="absolute -top-1 -right-1 bg-teal-600 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center"
    ></span>
  </button>

  <div
    x-show="$store.miniCart.isOpen"
    x-transition:enter="transition ease-out duration-200"
    x-transition:enter-start="opacity-0 translate-y-1"
    x-transition:enter-end="opacity-100 translate-y-0"
    x-transition:leave="transition ease-in duration-150"
    x-transition:leave-end="opacity-0"
    @click.outside="$store.miniCart.close()"
    @keydown.escape.window="$store.miniCart.close()"
    class="absolute right-0 mt-2 w-96 bg-white rounded-2xl shadow-xl border border-slate-200 z-40"
    x-cloak
  >
    <!-- items partial from section 6 -->
  </div>
</div>

Das @click.outside-Modifier und @keydown.escape.window sind für eine gute Mini Cart nicht optional. Ohne sie bleibt der Flyout offen, wenn der Kunde daneben klickt oder die Escape-Taste drückt, was auf Dauer als störend wahrgenommen wird. x-cloak verhindert zusätzlich das kurze Aufblitzen des Panels beim initialen Seitenaufbau, bevor Alpine die Direktiven ausgewertet hat.

6. Mini-Cart-Items mit x-for rendern

Die eigentliche Artikelliste im Flyout wird mit x-for über das items-Array des Stores gerendert. Jedes Item braucht einen stabilen :key, idealerweise die Item-ID aus dem Warenkorb, damit Alpine beim Aktualisieren der Liste bestehende DOM-Knoten wiederverwendet, statt sie komplett neu zu erzeugen.

Für eine ruhige Mini Cart Vorschau lohnt es sich, einen expliziten Leerzustand zu definieren, der angezeigt wird, wenn itemCount null ist. Ohne diesen Zustand sieht der Kunde nur ein leeres Panel und muss selbst erraten, ob der Warenkorb wirklich leer ist oder ob gerade ein Ladefehler vorliegt.

<div class="p-4 max-h-96 overflow-y-auto">
  <template x-if="$store.miniCart.isLoading">
    <p class="text-sm text-slate-500 py-8 text-center">Warenkorb wird aktualisiert …</p>
  </template>

  <template x-if="!$store.miniCart.isLoading && $store.miniCart.itemCount === 0">
    <p class="text-sm text-slate-500 py-8 text-center">Ihr Warenkorb ist noch leer.</p>
  </template>

  <template x-for="item in $store.miniCart.items" :key="item.id">
    <div class="flex gap-3 py-3 border-b border-slate-100 last:border-0">
      <img :src="item.product.thumbnail.url" :alt="item.product.name" class="w-14 h-14 rounded-lg object-cover flex-shrink-0" loading="lazy">
      <div class="flex-1 min-w-0">
        <p class="text-sm font-semibold text-slate-800 truncate" x-text="item.product.name"></p>
        <p class="text-xs text-slate-500" x-text="'Menge: ' + item.quantity"></p>
      </div>
      <p class="text-sm font-semibold text-slate-800" x-text="item.prices.row_total.value + ' €'"></p>
    </div>
  </template>
</div>

Der Einsatz von loading="lazy" auf den Produktbildern lohnt sich, sobald mehr als drei oder vier Artikel im Flyout angezeigt werden. Die Mini Cart lädt so nur die Bilder, die tatsächlich sichtbar sind, was besonders bei mobilen Verbindungen die Ladezeit des Flyouts spürbar verkürzt.

7. Menge ändern und Artikel entfernen im Flyout

Ein wirklich nützliches Mini Cart-Panel erlaubt es, die Menge direkt im Flyout zu ändern, ohne dass der Kunde auf die volle Warenkorbseite wechseln muss. Dafür wird pro Zeile eine updateQuantity-Methode im Store ergänzt, die einen Debounce nutzt, damit nicht bei jedem Klick auf den Stepper sofort ein Request abgesetzt wird.

Für das Entfernen eines Artikels reicht ein einfacher REST- oder GraphQL-Mutation-Aufruf, gefolgt von einem erneuten refresh(). Wichtig ist ein kurzer optischer Übergang, etwa ein Ausblenden der Zeile per x-transition, damit das Entfernen nicht abrupt wirkt und der Kunde die Änderung bewusst wahrnimmt.

Alpine.store('miniCart').pendingUpdate = null;

Alpine.store('miniCart').updateQuantity = function (itemId, quantity) {
  clearTimeout(this.pendingUpdate);
  this.pendingUpdate = setTimeout(async () => {
    await fetch('/graphql', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        query: `mutation UpdateCartItem($cartId: String!, $itemId: Int!, $qty: Float!) {
          updateCartItems(input: { cart_id: $cartId, cart_items: [{ cart_item_id: $itemId, quantity: $qty }] }) {
            cart { total_quantity }
          }
        }`,
        variables: { cartId: window.localStorage.getItem('mage-cart-id'), itemId, qty: quantity }
      })
    });
    this.refresh();
  }, 400);
};

Alpine.store('miniCart').removeItem = async function (itemId) {
  await fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `mutation RemoveCartItem($cartId: String!, $itemId: Int!) {
        removeItemFromCart(input: { cart_id: $cartId, cart_item_id: $itemId }) { cart { total_quantity } }
      }`,
      variables: { cartId: window.localStorage.getItem('mage-cart-id'), itemId }
    })
  });
  this.refresh();
};

Der Debounce von 400 Millisekunden hat sich in der Praxis als guter Kompromiss erwiesen: Er ist kurz genug, damit die Mini Cart nicht träge wirkt, aber lang genug, um mehrere schnelle Klicks auf den Stepper zu einem einzigen Request zu bündeln. Ohne Debounce entstehen bei jedem Klick separate Requests, die sich in ungünstiger Reihenfolge überholen können und zu einer falsch angezeigten Menge führen.

8. Fokus-Management und ARIA-Live-Region

Eine Mini Cart Vorschau, die nur visuell funktioniert, schließt Kunden mit Screenreader aus. Zwei Ergänzungen machen den Flyout barrierefrei: Erstens muss der Fokus beim Öffnen des Panels auf das erste interaktive Element springen, und beim Schließen zurück auf den auslösenden Button. Zweitens braucht die Anzahl-Aktualisierung im Icon eine aria-live-Region, damit Screenreader die Änderung automatisch ansagen, ohne dass der Kunde manuell zum Icon navigieren muss.

Die Kombination aus aria-haspopup, aria-expanded und einer korrekt gesetzten role="status"-Region ist der Unterschied zwischen einer Mini Cart, die nur optisch überzeugt, und einer, die auch mit Tastatur und Screenreader zuverlässig bedienbar ist.

<div
  x-data
  x-effect="if ($store.miniCart.isOpen) { $refs.firstFocusable?.focus() }"
>
  <!-- visually hidden live region, announces cart count changes -->
  <div class="sr-only" role="status" aria-live="polite" x-text="'Warenkorb: ' + $store.miniCart.itemCount + ' Artikel'"></div>

  <div x-show="$store.miniCart.isOpen" role="dialog" aria-label="Warenkorb Vorschau">
    <a x-ref="firstFocusable" href="/checkout/cart" class="block p-2">Zum Warenkorb</a>
  </div>
</div>

Diese x-effect-Anweisung reagiert automatisch, sobald sich isOpen ändert, und setzt den Fokus ohne zusätzlichen Event-Listener. Für Hyvä-Projekte gilt zusätzlich: Nach jedem Inline-<script>-Block muss $hyvaCsp->registerInlineScript() im .phtml stehen, damit die Content Security Policy den Alpine-Code nicht blockiert. Ohne diesen Aufruf funktioniert die Mini Cart lokal im Entwicklungsmodus, schlägt aber in Produktion mit aktivierter CSP fehl.

9. Mini-Cart-Patterns im Vergleich

Es gibt mehrere technische Wege, eine Mini Cart in einem Magento-Shop umzusetzen. Die Wahl hat direkten Einfluss auf Ladezeit, Server-Last und wie natürlich sich der Flyout anfühlt.

In der Praxis performt die Kombination aus globalem Alpine.store(), gezieltem GraphQL-Refresh und Event-basierter Kommunikation am besten. Sie hält die Mini Cart Vorschau leichtgewichtig, ohne auf Komfortfunktionen wie Mengenänderung oder Live-Ansagen zu verzichten, und bleibt dabei vollständig im Rahmen dessen, was Hyvä ohnehin an Tooling mitbringt.

10. Zusammenfassung

Eine gelungene Mini Cart Vorschau in Hyvä besteht aus wenigen, klar getrennten Bausteinen: einem globalen Alpine.store() für den Warenkorb-Zustand, einem Custom Event, das Formulare und Panel entkoppelt, gezieltem GraphQL-Nachladen statt schwerer Section-Data-Reloads, und einer sauberen Mengenänderung mit Debounce direkt im Flyout. Keine dieser Bausteine benötigt eine zusätzliche JavaScript-Bibliothek, alles läuft mit dem, was Alpine.js und Hyvä ohnehin mitbringen.

Der oft unterschätzte Teil ist die Barrierefreiheit: Fokus-Management beim Öffnen und Schließen sowie eine aria-live-Region für die Artikelzahl kosten wenig zusätzlichen Code, machen die Mini Cart aber für Screenreader-Nutzer erst wirklich bedienbar. Wer diese Punkte von Anfang an mitdenkt, spart sich spätere Nacharbeiten und baut einen Warenkorb-Flyout, der sowohl schnell als auch für alle Kunden zugänglich ist.

11. FAQ: Mini Cart Vorschau mit Alpine.js