Hyvä Theme Setup

Simpler Checkout ships a dedicated companion module for Hyvä Themes. The base module's Knockout/RequireJS integration doesn't render on Hyvä, so a separate package replaces it with a small JS + AJAX bridge that hooks into Hyvä's customer-data lifecycle.

When you need this

If your storefront uses any Hyvä-based theme — the Hyvä default, a custom child theme, or a third-party Hyvä theme — install this package in addition to the base simpler/magento-checkout module. The compat module activates automatically via the official hyva-themes/magento2-compat-module-fallback mechanism — no theme switch, no config flag. On Luma it stays out of the way, so it's safe to install on multi-storefront setups where some stores run Luma and others run Hyvä.

Installation

Install the companion package alongside the base module:

composer require simpler/magento-checkout-hyva
bin/magento module:enable Simpler_CheckoutHyva
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:clean

App ID, credentials, and per-surface toggles are configured the same way as the base module — see Setup your App ID & Settings on the Installation page. The compat module reads from the same admin section; no Hyvä-specific configuration screen.

What renders out of the box

Zero-config. The compat module mirrors the base module's surfaces on Hyvä:

Surface	Behaviour
Product page	Auto-injected as a full-width row below add-to-cart on simple, virtual, configurable, and bundle products.
Product page (configurable swatch change)	The button's payload updates live when the shopper picks a different variant — Luma's button is static, Hyvä's reflects the selected variant.
Minicart drawer	Rendered inside Hyvä's cart drawer alongside Proceed-to-Checkout.
Cart page	Rendered in the cart summary card, below the grand total.
Checkout / success pages	Same as Luma — server-rendered by the base module.

The same Magento admin flags gate every surface (see Button Configuration):

• simpler_checkout/settings/enable — master switch.
• show_in_product_view — controls the PDP auto-injection.
• show_in_cart_view — controls the cart-page and minicart-drawer buttons.

Customizing

Hide Simpler on a specific surface

Set show_in_product_view or show_in_cart_view to No in the Magento admin. The corresponding surface stops rendering — the compat module respects the same flags as the base module, so you don't need a Hyvä-specific override.

Move the product-page button to a different spot in your child theme

When you want Simpler on PDP but in a custom location in your child theme, render the <simpler-checkout> web component directly from a .phtml of your choice:

app/design/frontend/YourVendor/YourTheme/Simpler_Checkout/templates/custom-button.phtml

<simpler-checkout
    position="simpler.product.page"
    appId="<?= $block->escapeHtmlAttr($simplerAppId) ?>"
    locale="<?= $block->escapeHtmlAttr($locale) ?>"
    withAcceptedCards="true"
    fullWidth="true"
    payload="<?= $block->escapeHtmlAttr($payload) ?>">
</simpler-checkout>

Compute appId / locale / payload from one of the base-module ViewModels (Simpler\Checkout\ViewModel\SimpleProductButton, ConfigurableProductButton, BundleProductButton) — the same ViewModels documented in Button Style. The compat module handles sessionId automatically: a MutationObserver watches the DOM and injects the authenticated customer's session token onto every <simpler-checkout> element it sees, including elements your custom template renders later in the page lifecycle.

Two caveats when going this route:

• Set show_in_product_view → No in the admin first. Otherwise the default auto-injection runs alongside your custom embed and you'll see two buttons on the PDP.
• The configurable-product swatch-change wiring (live payload updates when the shopper picks a variant) is attached to the auto-injected element only. A hand-rolled embed on a configurable PDP shows the variant that was selected at page load, and won't update on swatch change. If you need live variant updates on your custom embed, the module README documents the JSON endpoint and event you can wire up from an Alpine component.

Render the button in a custom surface

For sticky add-to-cart bars, CMS blocks, custom Hyvä pages, or anywhere outside the default surfaces — the same <simpler-checkout> snippet works. Drop it in, populate the attributes from the appropriate ViewModel, and the compat module's session bridge picks it up.

If you'd rather render the button entirely from JavaScript (e.g. inside an Alpine component), the compat module exposes two JSON endpoints that return the attributes you need:

Endpoint	Use for	Response shape
/simpler/config/product?productId=<id>	PDP-like surfaces	{ shouldRender, position, attrs: { appId, locale, payload, withAcceptedCards } }
/simpler/config/checkout	Cart-like surfaces	{ shouldRender, attrs: { appId, locale, payload, withAcceptedCards } }

Fetch the relevant endpoint, check shouldRender (the same admin flags that gate the auto-injected surfaces gate this too), then materialize a <simpler-checkout> element with the returned attrs. A self-contained Alpine component for a PDP-like custom surface:

app/design/frontend/YourVendor/YourTheme/Magento_Catalog/templates/custom-simpler-button.phtml

<div
    x-data="{
        config: null,
        async init() {
            const res = await fetch('/simpler/config/product?productId=<?= (int) $block->getProduct()->getId() ?>');
            if (res.ok) this.config = await res.json();
        }
    }"
>
    <template x-if="config && config.shouldRender">
        <simpler-checkout
            :position="config.position"
            :appId="config.attrs.appId"
            :locale="config.attrs.locale"
            :payload="config.attrs.payload"
            :withAcceptedCards="String(config.attrs.withAcceptedCards)"
            fullWidth="true">
        </simpler-checkout>
    </template>
</div>

Notes:

• The <simpler-checkout> element is a web component shipped by the Simpler SDK, which the compat module's head.phtml already loads on every page — you don't need to load any additional script.
• Don't set sessionId yourself. As soon as the element enters the DOM, the compat module's MutationObserver picks it up and injects the authenticated customer's session token from window.hyva.getCustomerData('customer').
• withAcceptedCards is coerced to a string because the web component reads it as an HTML attribute, not a property — :withAcceptedCards="true" would serialize to the string "true" anyway, but String(...) is explicit about the intent.
• For cart-like surfaces, swap the endpoint for /simpler/config/checkout and drop the :position binding (the cart endpoint doesn't return a position because it's not surface-specific — set position="simpler.cart.page" or position="simpler.minicart" directly depending on where you're rendering).

To refresh the button when the cart changes (e.g. inside a custom minicart implementation), listen for Hyvä's private-content-loaded window event and re-fetch the same endpoint — that's exactly what the compat module's built-in JS does for the default minicart drawer.

Further reading

For deeper customization — the DOM selector contract the auto-injection relies on, event hooks, the internal architecture of the compat module, and details on calling the JSON endpoints directly — see the module README on GitLab.