Alpine.js patterns for Hyvä are the small, repeatable code shapes — x-data, x-cloak, $store, x-bind:class, x-on:click.outside, x-intersect, x-show, x-html, x-init, $dispatch — that show up across virtually every Hyvä module on Magento 2.4.4 — 2.4.9.^[1] Generic Alpine docs cover the directives but not hydrating from a Magento ViewModel, talking to Magewire, or the x-cloak trap that ships broken on most third-party Hyvä modules. Here are the ten that matter, with real snippets from production modules shipped through kishansavaliya.com.

Quick reference table

Pin this table to your editor before you open a Hyvä module — it answers "which directive do I reach for" without scrolling through the post.

Pattern	Use case	Directive
Server hydration	Cart count, customer name, store config from PHP	`x-data` + ViewModel JSON
Flash prevention	Hide swatches/tabs during Alpine boot	`x-cloak`
Global state	Mini-cart talking to PDP add-to-cart	`Alpine.store()`
Active tab UI	Highlight selected swatch, current tab	`x-bind:class`
Drawer dismissal	Close mini-cart on outside click	`x-on:click.outside`
Lazy load on scroll	PDP related products, footer widgets	`x-intersect`
Accordion / FAQ	Show/hide with transition	`x-show` + `x-transition`
Server HTML chunks	Insert PHP-rendered fragment safely	`x-html` + DOMPurify
Persist to storage	Last-viewed product, theme preference	`x-init` + `$watch`
Magewire bridge	Alpine drawer triggering server re-render	`$dispatch`

Hyvä is not "Alpine instead of Knockout". It is Alpine plus Magewire plus a server-rendered baseline. The patterns that matter are the ones that bridge those three.

1. Hydrate `x-data` from a ViewModel

Hydrate Alpine state from PHP at render time using x-data with a ViewModel that returns JSON — never a second AJAX request for data the server already has. Knockout-era Magento paid a 200–400 ms customer-data round-trip on every page load; Alpine can be hydrated inline.

The ViewModel

<?php
// app/code/Vendor/Module/ViewModel/CartState.php
namespace Vendor\Module\ViewModel;

use Magento\Checkout\Model\Session;
use Magento\Framework\View\Element\Block\ArgumentInterface;

class CartState implements ArgumentInterface
{
    public function __construct(private Session $checkoutSession) {}

    public function getJsonForAlpine(): string
    {
        $quote = $this->checkoutSession->getQuote();
        return json_encode([
            'count' => (int)$quote->getItemsQty(),
            'subtotal' => (float)$quote->getSubtotal(),
            'currency' => $quote->getQuoteCurrencyCode(),
        ], JSON_HEX_APOS | JSON_HEX_QUOT);
    }
}

The template

<?php $cart = $block->getViewModel(); ?>
<div x-data='{<?= $cart->getJsonForAlpine() ?>}' class="relative">
    <button @click="$store.cart.open()" class="flex items-center gap-2">
        <span>Cart</span>
        <span x-text="count" class="rounded-full bg-primary px-2 text-white"></span>
    </button>
</div>

When to reach for it: any time the initial state lives on the server (customer name, cart count, store view config, feature flags).

Trap: use JSON_HEX_APOS | JSON_HEX_QUOT so a quote in the data does not break the attribute, and never embed un-escaped customer strings — sanitize in PHP.

2. Prevent the flash with `x-cloak`

Block the un-Alpine-rendered DOM from flashing into view by combining x-cloak with a one-line CSS rule. On a cold Hyvä PDP, Alpine takes 80–200 ms to boot; without x-cloak, the customer sees raw swatches snap into place — which looks broken on a slow phone.

The template

<div x-data="{ activeSwatch: null }" x-cloak class="flex gap-2">
    <template x-for="swatch in ['red','blue','green']" :key="swatch">
        <button @click="activeSwatch = swatch"
                :class="activeSwatch === swatch ? 'ring-2 ring-primary' : 'ring-1 ring-gray-300'"
                class="h-10 w-10 rounded-full">
        </button>
    </template>
</div>

The CSS

<style>[x-cloak] { display: none !important; }</style>

When to reach for it: any Alpine block above the fold. PDP swatches, mini-cart trigger, header search.

Trap: the CSS rule must be inlined in the <head>, not loaded from an async CSS file — otherwise it arrives after the flash. Hyvä's tailwind/source.css already ships this; add it manually only if you have stripped Tailwind out.

3. Cross-component state with `Alpine.store()`

Share state across unrelated components using Alpine.store(), so the mini-cart drawer and the PDP add-to-cart button can talk without a parent in common. For ephemeral UI state — drawer open, recently added, search panel visible — Alpine's store API is lighter than Magewire and does not round-trip.

Register the store

// view/frontend/web/js/cart-store.js — loaded via default.xml <requirejs-config> equivalent
document.addEventListener('alpine:init', () => {
    Alpine.store('cart', {
        open: false,
        count: window.hyva.getCookie('section_data_cart')?.count ?? 0,
        toggle() { this.open = !this.open },
        addOne() { this.count += 1; this.open = true; }
    });
});

Consume it from anywhere

<!-- minicart drawer (header) -->
<aside x-show="$store.cart.open" x-transition.opacity class="fixed inset-y-0 right-0 w-96 bg-white">
    Items: <span x-text="$store.cart.count"></span>
</aside>

<!-- add-to-cart on PDP -->
<button @click="$store.cart.addOne()" class="btn-primary">Add to cart</button>

When to reach for it: two or more components that need the same state and do not share a parent.

Trap: never put server-authoritative data in $store (cart totals, stock, pricing) — the store wipes on every navigation. For server truth, use a ViewModel or Magewire.

4. Active-tab UI with `x-bind:class`

Toggle CSS classes off Alpine state with x-bind:class — shorthand :class — so active tab, selected swatch, and step indicators stay in sync without manual DOM work. This replaces 80% of the jQuery .addClass() / .removeClass() a Luma developer writes daily.

<div x-data="{ tab: 'description' }" class="pdp-tabs">
    <nav class="flex gap-4 border-b">
        <template x-for="id in ['description','specs','reviews']" :key="id">
            <button @click="tab = id"
                    :class="tab === id
                        ? 'border-b-2 border-primary text-primary font-semibold'
                        : 'text-gray-600 hover:text-gray-900'"
                    class="py-3 px-4 capitalize"
                    x-text="id"></button>
        </template>
    </nav>
    <section x-show="tab === 'description'" class="py-6">...description...</section>
    <section x-show="tab === 'specs'" class="py-6">...specs...</section>
    <section x-show="tab === 'reviews'" class="py-6">...reviews...</section>
</div>

When to reach for it: tabs, accordions, swatches, step indicators — anywhere a single source-of-truth variable drives one element's appearance.

Trap: :class and static class on the same element merge — do not duplicate the same Tailwind utility in both.

5. Outside-click dismissal with `x-on:click.outside`

Close drawers, dropdowns, and overlays on an outside click with x-on:click.outside — shorthand @click.outside — without writing a document-level listener. One directive replaces the entire mage/utils/click-outside dependency every Luma module shipped.

<div x-data="{ open: false }" class="relative">
    <button @click="open = !open" class="btn">Account</button>
    <div x-show="open"
         @click.outside="open = false"
         @keydown.escape.window="open = false"
         x-transition
         class="absolute right-0 mt-2 w-56 rounded-md bg-white shadow-lg">
        <a href="/customer/account" class="block px-4 py-2 hover:bg-gray-50">My account</a>
        <a href="/customer/account/logout" class="block px-4 py-2 hover:bg-gray-50">Log out</a>
    </div>
</div>

When to reach for it: mini-cart drawer, account dropdown, search panel, mega-menu.

Trap: the listener fires on any outside click — including the button that opened it. Alpine handles this only when the trigger is inside the same root x-data scope. Sibling trigger = immediate-close loop.

6. Lazy-load with `x-intersect`

Defer expensive PDP blocks — related products, recently viewed, reviews iframe — until they scroll into view by wrapping them in x-intersect. Uses IntersectionObserver under the hood and ships in Alpine's intersect plugin (Hyvä bundles it). A PDP that defers four below-the-fold widgets typically saves 200–400 ms of LCP-adjacent work on mid-range phones.^[2]

<section x-data="{ loaded: false, html: '' }"
         x-intersect.once="
             loaded = true;
             fetch('/related-products/sku/' + window.productSku)
                 .then(r => r.text())
                 .then(t => { html = t })"
         class="min-h-[400px]">
    <div x-show="!loaded" class="animate-pulse h-96 bg-gray-100 rounded"></div>
    <div x-show="loaded" x-html="html"></div>
</section>

When to reach for it: any below-the-fold block whose data costs an extra request or a database query.

Trap: always use x-intersect.once — bare x-intersect fires every time the element re-enters the viewport, triggering a fresh fetch on every scroll-back.

7. Accordion FAQ with `x-show` + `x-transition`

Build accordion-style FAQ widgets with x-show + x-transition when you need fine control over the open/close animation. Native <details> is fine for content-only FAQs; for a styled FAQ with smooth slide animation, Alpine wins.

<div x-data="{ active: null }" class="space-y-2">
    <template x-for="(item, idx) in faqs" :key="idx">
        <div class="rounded border">
            <button @click="active = active === idx ? null : idx"
                    class="w-full flex justify-between px-4 py-3 text-left">
                <span x-text="item.q"></span>
                <span x-text="active === idx ? '−' : '+'"></span>
            </button>
            <div x-show="active === idx"
                 x-transition:enter="transition ease-out duration-200"
                 x-transition:enter-start="opacity-0 -translate-y-2"
                 x-transition:enter-end="opacity-100 translate-y-0"
                 class="px-4 pb-4 text-gray-700"
                 x-text="item.a"></div>
        </div>
    </template>
</div>

When to reach for it: styled FAQs, mobile filter panels, mega-menu fly-outs.

Trap: x-show toggles display but keeps the element in the DOM — SEO and a11y tools see hidden content (usually what you want for FAQs). To physically remove from the DOM, use x-if on a <template> wrapper instead.

8. Server HTML chunks with `x-html` + DOMPurify

Render server-supplied HTML fragments through x-html only after passing the string through DOMPurify to neutralize XSS. x-html is Alpine's innerHTML — on a trusted internal endpoint, fine; on anything carrying user-generated content (review excerpts, customer-supplied URLs), sanitize first.

<script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>

<section x-data="{
    raw: '',
    safe() { return window.DOMPurify.sanitize(this.raw, { USE_PROFILES: { html: true } }) }
}"
         x-init="fetch('/reviews/api/list?sku=' + window.productSku)
                    .then(r => r.text())
                    .then(t => raw = t)">
    <div x-html="safe()"></div>
</section>

When to reach for it: any fetched HTML where the source is not 100% under your control.

Trap: never wrap a Magewire response in DOMPurify — it strips Magewire's hydration markers and breaks the next round-trip. Magewire output is already sanitized server-side; use x-html directly there.

9. Persist to localStorage with `x-init` + `$watch`

Persist UI state — theme preference, last-viewed product, dismissed banner — to localStorage using x-init to hydrate from storage and $watch to write back on every change. Gives a Hyvä site "sticky" behavior across navigation without a cookie round-trip or a server session.

<div x-data="{
        theme: 'light',
        init() {
            this.theme = localStorage.getItem('kc.theme') || 'light';
            this.$watch('theme', v => localStorage.setItem('kc.theme', v));
        }
     }"
     :class="theme === 'dark' ? 'bg-gray-900 text-white' : 'bg-white text-gray-900'">
    <button @click="theme = theme === 'dark' ? 'light' : 'dark'" class="btn">
        <span x-text="theme === 'dark' ? 'Light mode' : 'Dark mode'"></span>
    </button>
</div>

When to reach for it: theme toggle, dismissed announcement bars, recently-viewed SKUs, last-selected store view.

Trap: never put PII or sensitive data (customer email, order numbers) in localStorage — every script on the origin can read it, including third-party tags. Use a backend session or the encrypted cookie API instead.

10. Magewire bridge with `$dispatch`

Bridge Alpine.js to Magewire using $dispatch — Alpine emits a browser CustomEvent, Magewire listens via wire:listen, and the server re-renders. The most under-documented Hyvä pattern, and the one that unlocks the "Alpine for ephemeral state, Magewire for server truth" architecture Hyvä is built around.^[3]

Alpine emits

<button @click="$dispatch('cart-item-added', { sku: 'ABC-123', qty: 1 })"
        class="btn-primary">
    Add to cart
</button>

Magewire listens and re-renders

<?php
// app/code/Vendor/Module/Magewire/Header/MiniCart.php
namespace Vendor\Module\Magewire\Header;

use Magewirephp\Magewire\Component;
use Magento\Checkout\Model\Session;

class MiniCart extends Component
{
    public int $count = 0;

    protected $listeners = [
        'cart-item-added' => 'onItemAdded',
    ];

    public function __construct(private Session $checkoutSession) {}

    public function mount(): void
    {
        $this->count = (int)$this->checkoutSession->getQuote()->getItemsQty();
    }

    public function onItemAdded(array $payload): void
    {
        $this->count = (int)$this->checkoutSession->getQuote()->getItemsQty();
    }
}

Magewire template

<div wire:id="mini-cart" class="flex items-center gap-2">
    Cart (<span><?= (int)$this->count ?></span>)
</div>

When to reach for it: any Alpine ↔ server handoff — add-to-cart, wishlist toggle, applied coupon, address selection.

Trap: Magewire listeners are page-scoped — they do not survive a full navigation. $dispatch is for in-page reactivity only; for cross-page state use a session or query parameter.

Alpine for ephemeral UI state. Magewire for server truth. $dispatch is the bridge. Get this division right and the module is half-built.

The Hyvä-specific gotchas to know

Three Hyvä behaviors are not in the Alpine docs and bite first-time devs. Hyvä exposes Magento's customer-data as a cookie-backed object at window.hyva.getCookie('section_data_cart') that hydrates synchronously before Alpine boots — read it inside x-data directly. Hyvä-React-Checkout does not use Alpine and does not listen to $dispatch; use the hyva-checkout event bus there. And Hyvä 1.3+ pins to Alpine v3 — v2 patterns like x-model.debounce will silently no-op.^[4]

Where Alpine is the wrong choice

Alpine is the wrong choice in three situations. Heavy client-side rendering of 200+ nodes from a JSON array will feel sluggish — server-render the list and attach a small x-data scope per row. Multi-step forms with cross-field validation are easier in Magewire. And anything that depends on stock, pricing, or customer group belongs in PHP — Alpine should be the thin reactive layer over server data, not the place where business rules live.

FAQ

Do I need to learn Alpine.js to build Hyvä modules?

Yes — Alpine is the frontend reactivity layer in Hyvä. Alpine has roughly 15 directives total, and the ten in this post cover ~90% of real-world Hyvä module work. A Magento backend developer is productive in Alpine after one focused day.

When should I use Alpine vs Magewire on Hyvä?

Use Alpine for client-side ephemeral state — drawer open, active tab, modal visible. Use Magewire when the server is the source of truth — cart totals, stock, pricing, customer data. Use $dispatch as the bridge. Rule of thumb: if a page refresh erasing the state is correct, it is Alpine; if a refresh should preserve it, Magewire.

How do I debug an Alpine component that is not reacting?

Open DevTools, install the Alpine.js Devtools browser extension, and inspect the component. Nine times out of ten the issue is one of: x-data JSON syntax error (check the console), the alpine:init listener registered after Alpine booted, or a typo in a directive name — Alpine silently ignores unknown directives.

Is Alpine.js v3 fast enough for a 200-product PLP?

Yes, when used correctly. The PLP itself should be server-rendered with Alpine reactivity only on per-card actions (wishlist toggle, quick-add). Do not render the full 200-product list from a JSON array in x-data — that is the path to a sluggish reactivity loop. Server-render the cards, attach a small x-data scope to each, and Alpine stays out of the way.

What changes when Hyvä upgrades from 1.3 to 1.4?

Alpine v3 stays. The patterns above stay. The bundled plugin set may change (Hyvä occasionally adds focus or collapse to the default bundle). The ten patterns in this post are stable across Hyvä 1.2, 1.3, and the public 1.4 roadmap.

References

Alpine.js project documentation, Directives — alpinejs.dev/directives. Reference for x-data, x-cloak, x-show, x-bind, x-on, x-init, x-html.
Web.dev, Lazy-loading offscreen content with IntersectionObserver — the browser API underlying Alpine's x-intersect plugin.
Magewire project documentation, Events and Listeners — github.com/magewirephp/magewire. Reference for wire:listen, $listeners, and the browser event bridge.
Hyvä Themes documentation, Alpine.js in Hyvä — covers the bundled plugin set, the alpine:init lifecycle, and the supported Alpine version.
Production Hyvä module engagements via kishansavaliya.com, 2024 — 2026. Patterns extracted from 40+ shipped modules across Magento 2.4.4 — 2.4.9.

Need a Hyvä module shipped this sprint?

I am Kishan Savaliya, an Adobe-Certified Magento + Hyvä developer. I ship fixed-scope Hyvä modules — configurators, B2B quick-order grids, custom checkout steps — using the ten patterns above plus Magewire where the server owns the truth. Fixed quote from $499 audit · $2,499 sprint · ~30h @ $25/hr. See Hyvä theme development or hire me.

Tagged #Hyvä #Tailwind #Alpine.js #Alpine Patterns #Frontend

Keep reading

Hyvä Checkout Customization — 5 Real Patterns from Production Stores

Five Hyvä Checkout customizations that actually shipped on production Magento 2.4.4 — 2.4.9 stores — what the merchant asked for, what was tricky, and the code shape. Google Places address autocomplete bound to the Magewire shipping component via an Alpine.js bridge. CPF for Brazil / VAT for the EU as reactive Magewire fields with wire:model.live. Runtime carrier filtering through a collectShippingRates plugin. A post-purchase upsell Magewire component on the success page with one-click PayPal Express. Locale-aware date pickers via the Hyvä i18n partial. For each: the trigger, the file shape, the gotcha.

May 20, 2026
Hyvä Module Compatibility Checker — Manual Grep + Automated CLI

There are two honest ways to check whether a Magento extension is Hyvä-compatible — manual grep across the module source, and the hyva-themes/magento2-compatibility-checker CLI. Neither one catches everything. This post lists the exact bash one-liners I run against vendor/, walks through what the official Hyvä compat CLI flags and what it silently ignores (Magewire deps, GraphQL schema needs, form validation libs), and ends with the checklist I work through when the CLI prints "compatible" but the module still throws KO errors in the Hyvä storefront on Magento 2.4.4 — 2.4.9.

May 20, 2026
Hyvä Checkout Custom Field — A Working Delivery-Date Example

Most Hyvä checkout customization tutorials stop at "render a field" and skip the backend plumbing that actually persists the value to the order. Here is a complete, copy-pasteable delivery_date field for Hyvä Checkout 1.2+ on Magento 2.4.4 — 2.4.9: the Magewire vs Alpine.js decision tree, the extension_attributes.xml declaration, the Magewire component class, the date input partial with HTML5 min/max constraints, the QuoteRepository save plugin, and the admin sales_order_view.xml display. Plus the gotcha that breaks guest checkouts: the date does not survive submitQuote without a second plugin.

May 20, 2026

Quick reference table

1. Hydrate x-data from a ViewModel

The ViewModel

The template

2. Prevent the flash with x-cloak

The template

The CSS

3. Cross-component state with Alpine.store()

Register the store

Consume it from anywhere

4. Active-tab UI with x-bind:class

5. Outside-click dismissal with x-on:click.outside

6. Lazy-load with x-intersect

7. Accordion FAQ with x-show + x-transition

8. Server HTML chunks with x-html + DOMPurify

9. Persist to localStorage with x-init + $watch

10. Magewire bridge with $dispatch

Alpine emits

Magewire listens and re-renders

Magewire template

The Hyvä-specific gotchas to know

Where Alpine is the wrong choice

FAQ

Related reading

References

Hyvä Checkout Customization — 5 Real Patterns from Production Stores

Hyvä Module Compatibility Checker — Manual Grep + Automated CLI

Hyvä Checkout Custom Field — A Working Delivery-Date Example

1. Hydrate `x-data` from a ViewModel

2. Prevent the flash with `x-cloak`

3. Cross-component state with `Alpine.store()`

4. Active-tab UI with `x-bind:class`

5. Outside-click dismissal with `x-on:click.outside`

6. Lazy-load with `x-intersect`

7. Accordion FAQ with `x-show` + `x-transition`

8. Server HTML chunks with `x-html` + DOMPurify

9. Persist to localStorage with `x-init` + `$watch`

10. Magewire bridge with `$dispatch`