Hyvä-Minicart anpassen: Verhalten und Darstellung erweitern

1. Aufbau der Hyvä-Minicart-Komponente

Die Hyvä-Minicart lebt im Kern in einer einzigen Template-Datei: app/design/frontend/Mironsoft/default/Magento_Checkout/templates/cart/minicart.phtml, die das Parent-Theme hyva-themes/magento2-default-theme-csp überschreibt. Der Root-Container trägt x-data="initMinicart()", eine Alpine-Factory-Funktion, die den kompletten Zustand der Komponente kapselt: Ladezustand, Sichtbarkeit des Panels, geladene Warenkorbdaten und Fehlerinformationen. Statt Knockout-Observables mit ko.observable() und einem separaten .html-Template pro Binding arbeitet die Hyvä-Minicart mit einem einzigen JavaScript-Objekt, dessen Eigenschaften Alpine über x-text, x-show und x-for direkt an das Markup bindet.

Die Warenkorbdaten selbst kommen nicht mehr aus dem serverseitig gerenderten Customer-Data-Storage, sondern aus einer GraphQL cart query, die die Alpine-Komponente per fetch() gegen den /graphql-Endpunkt absetzt. Das ersetzt den kompletten Mechanismus aus Magento_Customer/js/customer-data, private Content-Sections und dem globalen customer-data-invalidate-Event. Wer diese Komponente anpassen möchte, muss also an zwei Stellen ansetzen: am Markup und den Alpine-Direktiven in minicart.phtml, und an der GraphQL-Query, die die Rohdaten liefert.

Wichtig für die Darstellung der Minicart ist, dass der Hyvä-Block-Mechanismus dabei erhalten bleibt: $block->getChildNames() wird weiterhin iteriert, um zusätzliche Blöcke wie Cross-Sell-Widgets oder Versandhinweise einzuhängen. Alpine ersetzt nur die client-seitige Reaktivität, nicht das serverseitige Block-System von Magento. Diese Trennung ist entscheidend, wenn man sie erweitern will, ohne die Layout-XML-Steuerung aufzugeben.

<!-- app/design/frontend/Mironsoft/default/Magento_Checkout/templates/cart/minicart.phtml -->
<?php
/** @var \Magento\Checkout\Block\Cart\Sidebar $block */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<div
  x-data="initMinicart()"
  x-init="fetchSummaryOnly()"
  @private-content-loaded.window="fetchSummaryOnly()"
  class="relative"
>
  <!-- Trigger button: icon + badge, see section 2 -->
  <button
    type="button"
    @click="open = true; !hydrated && fetchCart()"
    class="relative inline-flex items-center justify-center p-2"
    :aria-expanded="open.toString()"
    aria-controls="minicart-panel"
  >
    <span class="sr-only">Warenkorb öffnen</span>
    <!-- inline SVG icon lives here, no icon font -->
  </button>

  <!-- Slide-in panel, see section 4 -->
  <div
    id="minicart-panel"
    x-show="open"
    x-cloak
    role="dialog"
    aria-modal="true"
    @click.away="open = false"
    @keydown.escape.window="open = false"
    class="absolute right-0 mt-2 w-96 bg-white rounded-2xl shadow-xl border border-slate-200"
  >
    <template x-if="loading">
      <div class="p-6 text-sm text-slate-500">Warenkorb wird geladen &hellip;</div>
    </template>

    <template x-if="!loading && cart.items.length === 0">
      <div class="p-6 text-sm text-slate-500">Dein Warenkorb ist leer.</div>
    </template>

    <template x-for="item in cart.items" :key="item.uid">
      <div class="flex gap-3 p-4 border-b border-slate-100">
        <img :src="item.product.thumbnail.url" :alt="item.product.name" class="w-16 h-16 object-cover rounded-lg" loading="lazy">
        <div class="flex-1">
          <p class="text-sm font-semibold" x-text="item.product.name"></p>
          <p class="text-xs text-slate-500" x-text="item.quantity + ' x ' + item.prices.price.value + ' EUR'"></p>
        </div>
      </div>
    </template>

    <?= $block->getChildHtml('minicart.extra') ?>
  </div>
</div>

<script>
  <?= /* @noEscape */ '' ?>
</script>
<?php $hyvaCsp->registerInlineScript(); ?>

2. Minicart-Icon und Badge anpassen

Das Icon der Hyvä-Minicart ist bewusst kein Icon-Font, sondern ein inline <svg>, das direkt im Markup von minicart.phtml liegt. Das entspricht der Vorgabe, keine zusätzlichen Custom-Fonts zu laden: Ein SVG-Pfad kostet kein zusätzliches Font-Request, lässt sich per Tailwind-Klassen (w-6 h-6 text-slate-700) einfärben und reagiert ohne Zusatzaufwand auf hover:- und focus-visible:-Zustände. Wer das Icon im Header optisch anpassen will, tauscht schlicht den SVG-Pfad aus oder bindet ein zweites Icon-Set über eine eigene icons.phtml-Partial ein, die per $block->getChildHtml() eingebunden wird.

Die Artikelanzahl im Badge ist rein reaktiver Alpine-State: x-show="cart.total_quantity > 0" auf einem kleinen <span>, das absolut über dem Icon positioniert ist, mit x-text="cart.total_quantity" als Inhalt. Weil total_quantity Teil der GraphQL cart query ist, aktualisiert sich der Badge automatisch, sobald die Komponente nach einer Mutation neu synchronisiert wird, ganz ohne manuelles DOM-Update. Genau das ist der Kernvorteil, wenn man die Darstellung des Minicart-Panels erweitert: Ein einziger reaktiver Zustand steuert Icon, Badge und Panel-Inhalt gleichzeitig.

Die Sichtbarkeits-Logik bei leerem Warenkorb verdient besondere Aufmerksamkeit. Ohne x-cloak blitzt der Badge kurz auf, bevor Alpine hydriert hat, weil das Server-Markup keinen Anfangswert kennt. Die Kombination aus x-cloak im CSS (Hyvä liefert [x-cloak] { display: none !important; } bereits im Basis-Stylesheet) und einem initialen total_quantity: null im Alpine-State verhindert, dass die Hyvä-Minicart beim ersten Seitenaufruf kurzzeitig eine falsche Zahl zeigt.

3. Inhalte der Minicart erweitern

Cross-Sell-Produkte, Versandkosten-Hinweise oder Rabatt-Banner lassen sich in die Hyvä-Minicart einhängen, ohne die Kernlogik von minicart.phtml anzufassen. Der saubere Weg führt über Layout-XML: Ein eigener Block wird als Child des Minicart-Blocks registriert, zum Beispiel <referenceBlock name="minicart"><block class="Mironsoft\MinicartExtend\Block\FreeShippingHint" name="minicart.freeshipping.hint" template="Mironsoft_MinicartExtend::minicart/freeshipping-hint.phtml" /></referenceBlock>. In minicart.phtml wird der Block dann über $block->getChildHtml('minicart.freeshipping.hint') an der gewünschten Stelle ausgegeben, exakt nach dem bestehenden Hyvä-Muster der Child-Block-Iteration.

Für den Versandkostenfreigrenze-Hinweis liest eine ViewModel-Klasse den konfigurierten Schwellenwert aus Magento\Shipping\Model\Config beziehungsweise der jeweiligen Carrier-Konfiguration und übergibt ihn als Datenattribut an das Panel. Der Fortschrittsbalken selbst bleibt reaktiv: x-bind:style="{ width: Math.min(100, (cart.prices.grand_total.value / freeShippingThreshold) * 100) + '%' }". So aktualisiert sich der Balken automatisch, sobald sich der Warenkorbwert durch eine Mengenänderung verschiebt, ohne dass der Server erneut angefragt werden muss.

Cross-Sell-Produkte werden idealerweise per eigener GraphQL-Query nachgeladen, sobald die Minicart geöffnet wird, statt sie in jede Seiten-Antwort einzubetten. Das hält die initiale Payload klein und vermeidet, dass die Minicart bei jedem Klick auf eine Produktseite unnötig Cross-Sell-Daten mitschleppt, die der Nutzer vielleicht nie zu Gesicht bekommt.

<?php
declare(strict_types=1);

namespace Mironsoft\MinicartExtend\ViewModel;

use Magento\Framework\View\Element\Block\ArgumentInterface;
use Magento\Shipping\Model\Config as ShippingConfig;
use Magento\Store\Model\StoreManagerInterface;

/**
 * Provides the free shipping threshold used by the Hyva minicart hint block.
 */
final class FreeShippingThreshold implements ArgumentInterface
{
    /**
     * @param ShippingConfig $shippingConfig Reads active carrier configuration.
     * @param StoreManagerInterface $storeManager Resolves the current store scope.
     */
    public function __construct(
        private readonly ShippingConfig $shippingConfig,
        private readonly StoreManagerInterface $storeManager,
    ) {
    }

    /**
     * Returns the configured free shipping subtotal for the current store, or null if disabled.
     *
     * @return float|null
     */
    public function getThreshold(): ?float
    {
        $storeId = (int) $this->storeManager->getStore()->getId();
        $value = $this->shippingConfig->getValue('freeshipping/free_shipping_subtotal', $storeId);

        return $value !== null ? (float) $value : null;
    }
}

4. Slide-in/Dropdown-Verhalten anpassen

Das Öffnen und Schließen der Hyvä-Minicart ist reines Alpine-Verhalten über x-show="open" in Kombination mit x-transition-Direktiven, ganz ohne jQuery slideToggle() oder manuell geschriebene CSS-Keyframes. Für den Desktop-Dropdown genügt x-transition:enter="transition ease-out duration-200" x-transition:enter-start="opacity-0 scale-95" x-transition:enter-end="opacity-100 scale-100", während die mobile Drawer-Variante horizontal einfährt: x-transition:enter-start="translate-x-full" x-transition:enter-end="translate-x-0". Beide Varianten leben in derselben Komponente, gesteuert allein über Tailwind-Breakpoint-Klassen am Panel-Container.

Zum Schließen bei Klick außerhalb des Panels dient @click.away="open = false" direkt am Panel-Root. Ergänzend fängt @keydown.escape.window="open = false" die Escape-Taste global ab, was für Tastaturnutzer unverzichtbar ist. Ohne diese beiden Direktiven bleibt das Panel offen, sobald der Nutzer irgendwo anders auf die Seite klickt, was in Usability-Tests regelmäßig als Fehler auffällt.

Fokus-Management ist der Teil, der am häufigsten vergessen wird, wenn Teams sie anpassen: Beim Öffnen sollte der Fokus programmatisch auf das erste interaktive Element im Panel springen (x-init="$watch('open', value => value && $nextTick(() => $refs.closeButton.focus()))"), und beim Schließen zurück auf den auslösenden Trigger-Button. Das Panel selbst braucht role="dialog", aria-modal="true" und einen beschreibenden aria-label, damit Screenreader den Kontextwechsel korrekt ansagen.

5. GraphQL-Queries für die Minicart anpassen und erweitern

Die Standard-GraphQL cart query liefert bereits items, prices und total_quantity, aber sobald die Minicart erweitert werden soll, etwa um einen individuellen Rabatt-Hinweis pro Artikel, reicht das Kern-Schema nicht mehr aus. Der saubere Weg ist ein eigenes Modul mit einer etc/schema.graphqls-Erweiterung, die ein zusätzliches Feld an CartItemInterface anhängt, statt das Kernschema von Magento zu verändern. Der Resolver wird über etc/graphql/di.xml registriert und implementiert Magento\Framework\GraphQl\Query\ResolverInterface.

Overreporting ist das größte Performance-Risiko bei GraphQL-Queries für die Minicart: Wer aus Bequemlichkeit ein komplettes Produkt-Fragment mit Beschreibung, Meta-Daten und allen Bildvarianten anfragt, lädt bei jedem Minicart-Öffnen unnötig viel Payload. Die Query sollte exakt die Felder enthalten, die minicart.phtml tatsächlich rendert, nicht mehr. Ein eigenes GraphQL-Fragment pro Ansicht (fragment MinicartItemFields on CartItemInterface) macht diese Disziplin im Code sichtbar und wiederverwendbar.

# GraphQL query used by the Alpine minicart component
# File reference: Mironsoft_MinicartExtend/etc/schema.graphqls extends CartItemInterface

query MinicartData($cartId: String!) {
  cart(cart_id: $cartId) {
    id
    total_quantity
    items {
      uid
      quantity
      product {
        name
        sku
        thumbnail {
          url
        }
      }
      prices {
        price {
          value
          currency
        }
      }
      # Custom field added via Mironsoft_MinicartExtend, not part of core schema
      free_shipping_remaining
    }
    prices {
      grand_total {
        value
        currency
      }
    }
  }
}

# schema.graphqls extension (custom module)
type CartItemInterface {
  free_shipping_remaining: Float
    @resolver(class: "Mironsoft\\MinicartExtend\\Model\\Resolver\\FreeShippingRemaining")
}

6. Mengenänderung und Entfernen von Artikeln

Mengenänderungen in der Hyvä-Minicart laufen über x-model.debounce.500ms auf dem Mengenfeld, damit nicht bei jedem Tastendruck eine GraphQL-Mutation ausgelöst wird. Erst nach 500 Millisekunden Inaktivität feuert Alpine das @change-Handler, der die updateCartItems-Mutation gegen /graphql absetzt. Dazwischen zeigt die Oberfläche bereits den neuen Wert an, ein klassisches Optimistic-UI-Muster: Der lokale Alpine-State wird sofort aktualisiert, während die Mutation im Hintergrund läuft.

Schlägt die Mutation fehl, etwa weil der Lagerbestand nicht ausreicht, muss die Minicart den vorherigen Wert wiederherstellen und eine Inline-Fehlermeldung neben dem betroffenen Artikel anzeigen. Der Alpine-State hält dafür pro Artikel-UID sowohl den zuletzt bestätigten als auch den optimistisch gesetzten Wert vor, sodass ein Rollback ohne kompletten Refetch möglich ist. Für das Entfernen eines Artikels gilt dasselbe Muster mit der removeItemFromCart-Mutation: Der Eintrag verschwindet sofort aus der lokalen Liste, wird aber bei einem GraphQL-Fehler wieder eingefügt.

// app/design/frontend/Mironsoft/default/Magento_Checkout/web/js/minicart.js
function initMinicart() {
  return {
    open: false,
    loading: true,
    hydrated: false,
    cart: { items: [], total_quantity: 0, prices: { grand_total: { value: 0 } } },
    pendingQuantities: {},
    errors: {},

    async fetchCart() {
      this.loading = true;
      const response = await this.graphqlQuery(MINICART_QUERY, { cartId: this.getCartId() });
      this.cart = response.data.cart;
      this.hydrated = true;
      this.loading = false;
    },

    // Debounced via x-model.debounce.500ms in the template, called on @change
    async updateQuantity(uid, newQuantity) {
      const previous = this.cart.items.find((item) => item.uid === uid).quantity;
      this.optimisticSet(uid, newQuantity);

      try {
        const response = await this.graphqlMutation(UPDATE_CART_ITEMS_MUTATION, {
          cartId: this.getCartId(),
          cartItemUid: uid,
          quantity: newQuantity,
        });
        this.cart = response.data.updateCartItems.cart;
        delete this.errors[uid];
        window.dispatchEvent(new CustomEvent('minicart-updated', { detail: { quantity: this.cart.total_quantity } }));
      } catch (error) {
        this.optimisticSet(uid, previous);
        this.errors[uid] = 'Menge konnte nicht aktualisiert werden';
      }
    },

    async removeItem(uid) {
      const backup = [...this.cart.items];
      this.cart.items = this.cart.items.filter((item) => item.uid !== uid);

      try {
        const response = await this.graphqlMutation(REMOVE_ITEM_MUTATION, {
          cartId: this.getCartId(),
          cartItemUid: uid,
        });
        this.cart = response.data.removeItemFromCart.cart;
        window.dispatchEvent(new CustomEvent('minicart-updated', { detail: { quantity: this.cart.total_quantity } }));
      } catch (error) {
        this.cart.items = backup;
        this.errors[uid] = 'Artikel konnte nicht entfernt werden';
      }
    },

    optimisticSet(uid, quantity) {
      const item = this.cart.items.find((entry) => entry.uid === uid);
      if (item) {
        item.quantity = quantity;
      }
    },
  };
}

7. Eigene Events und Komponentenkommunikation

Der Trigger-Button im Header, das Minicart-Panel und die Produktseite liegen in unterschiedlichen Templates und damit auch in unterschiedlichen Alpine-Komponenten. Statt sie über verschachtelte x-data-Hierarchien zu koppeln, kommunizieren sie über native Browser-Events: window.dispatchEvent(new CustomEvent('minicart-updated', { detail: { quantity } })) nach jeder erfolgreichen Mutation, und window.addEventListener('minicart-updated', handler) überall dort, wo auf die neue Artikelanzahl reagiert werden muss.

Dieses Muster ersetzt den globalen jQuery-Event-Bus, den Luma-Themes über Magento_Customer/js/customer-data und das Event customer-data-invalidate nutzen. Auf der Produktdetailseite löst der Button "In den Warenkorb" nach der addProductsToCart-Mutation dasselbe minicart-updated-Event aus, sodass sich die Hyvä-Minicart im Header aktualisiert, ohne dass Produktseite und Minicart voneinander wissen müssen. Diese Entkopplung macht es einfach, sie in weiteren Kontexten wiederzuverwenden, etwa in einer Sticky-Header-Variante oder einem separaten Mobile-Menü.

8. Styling mit Tailwind CSS v4 anpassen

Tailwind CSS v4 nutzt einen CSS-first-Ansatz: Statt einer JavaScript-Konfigurationsdatei definiert ein @theme-Block in app/design/frontend/Mironsoft/default/Magento_Theme/web/tailwind/tailwind.css die Design-Tokens, etwa --color-minicart-badge: oklch(0.65 0.2 25);. Diese Tokens stehen dann als Utility-Klassen wie bg-minicart-badge in der gesamten Minicart zur Verfügung, ohne dass eine zusätzliche CSS-Datei gepflegt werden muss.

Responsives Verhalten löst sich rein über Breakpoint-Präfixe: Auf Mobile ist das Panel ein fixierter Drawer über fixed inset-y-0 right-0 w-full, ab dem sm:-Breakpoint wird daraus ein positionierter Dropdown mit sm:absolute sm:inset-auto sm:right-0 sm:top-full sm:w-96 sm:rounded-2xl. Beide Varianten teilen sich dieselbe Alpine-Logik für open, nur die Tailwind-Klassen am Panel-Container unterscheiden sich je nach Bildschirmgröße.

Zustände wie hover, focus und disabled werden ausschließlich über Tailwind-Modifier abgebildet: disabled:opacity-50 disabled:cursor-not-allowed auf dem Mengenfeld während einer laufenden Mutation, focus-visible:ring-2 focus-visible:ring-offset-2 auf dem Schließen-Button für Tastaturnutzer, group-hover:bg-slate-50 auf der Artikelzeile für visuelles Feedback. Kein einziges dieser Verhalten benötigt zusätzliches CSS außerhalb der Tailwind-Utility-Klassen.

9. Performance: Lazy Loading und Caching der Minicart-Daten

Die Hyvä-Minicart ist aus Sicht des Full Page Cache private content: Ihr Inhalt unterscheidet sich pro Kunde und darf nicht in der gecachten HTML-Hülle der Seite landen. Der Server liefert daher nur einen leeren Container mit x-data="initMinicart()", während die eigentlichen Warenkorbdaten client-seitig per GraphQL nachgeladen werden. Das hält die Seite selbst vollständig cachefähig und verlagert die einzige variable Information, die maskierte Cart-ID beziehungsweise das Kunden-Token, in den Browser-Speicher statt in den HTML-Response.

Damit nicht bei jedem einzelnen Seitenaufruf eine vollständige cart-Query gegen /graphql geschossen wird, lohnt sich ein zweistufiges Ladeverhalten: Beim ersten Rendern fragt die Komponente nur eine schlanke total_quantity-Summary an (siehe fetchSummaryOnly() in Abschnitt 1), um den Badge zu befüllen. Die vollständige Artikelliste inklusive Bildern und Preisen wird erst nachgeladen, wenn der Nutzer das Panel tatsächlich öffnet, ein klassisches Lazy-Loading-Muster, das unnötige GraphQL-Requests auf Seiten vermeidet, auf denen der Nutzer die Minicart nie aufklappt.

Zusätzlich lässt sich der zuletzt bekannte Summary-Wert im sessionStorage zwischenspeichern, damit ein Seitenwechsel den Badge nicht kurzzeitig auf null zurückfallen lässt, bevor die neue GraphQL-Antwort eintrifft. Sobald eine Mutation die Warenkorbdaten ändert, wird der Cache-Eintrag aktualisiert und das minicart-updated-Event aus Abschnitt 7 sorgt dafür, dass alle Instanzen des Minicart-Panels auf der Seite synchron bleiben.

// sessionStorage payload cached under key "mironsoft-minicart-summary"
// Read on x-init before the first GraphQL summary request completes,
// avoids a visible flash of "0" while the network request is in flight.
{
  "cartId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "totalQuantity": 3,
  "grandTotal": {
    "value": 129.90,
    "currency": "EUR"
  },
  "cachedAt": "2026-07-23T09:14:02.000Z"
}

Damit die Hyvä-Minicart nicht unnötig oft nachgeladen wird, genügt in der Regel ein einziger Trigger-Punkt pro Session: das Öffnen des Panels selbst. Alle weiteren Aktualisierungen erfolgen ereignisgesteuert nach Mutationen, nicht durch periodisches Polling. Das reduziert die Zahl der GraphQL-Requests auf ein Minimum, ohne dass die Darstellung der Minicart veraltet wirkt.

Der Vergleich zeigt den durchgängigen Unterschied: Wo Knockout und jQuery eine eigene Infrastruktur aus Observables, Sections und globalen Events brauchen, genügt der Hyvä-Minicart ein einziges Alpine-Objekt plus GraphQL-Mutationen. Das reduziert nicht nur die Menge an JavaScript, sondern auch die Anzahl der Stellen, an denen beim Anpassen ein Fehler entstehen kann.

10. Zusammenfassung

Die Hyvä-Minicart anzupassen bedeutet, an drei Ebenen gleichzeitig zu arbeiten: am Markup und den Alpine-Direktiven in minicart.phtml, an der GraphQL cart query samt eigener Schema-Erweiterungen, und an der Tailwind-CSS-Darstellung für Mobile-Drawer und Desktop-Dropdown. Icon und Badge sind reiner Alpine-State ohne Custom-Fonts, Cross-Sell-Inhalte werden per Layout-XML und getChildHtml() eingehängt, und Mengenänderungen laufen über debounced GraphQL-Mutationen mit optimistischen UI-Updates.

Wer die Minicart erweitern will, sollte konsequent zwischen serverseitigem Block-System und client-seitiger Alpine-Reaktivität trennen: Layout-XML steuert, welche Blöcke existieren, Alpine steuert, wie sie sich verhalten. Für die Performance gilt die einfache Regel, dass die Minicart als private content behandelt wird, ihre Daten erst bei Bedarf lädt und Statusänderungen über native CustomEvents statt globaler jQuery-Events verteilt. So bleibt die Hyvä-Minicart schnell, wartbar und vollständig kompatibel mit dem Full Page Cache.

11. FAQ: Hyvä-Minicart anpassen