Table of Contents & Menu
On this page
Navigation

7. Luma Theme Fallback

Important

To enable the Luma theme fallback, install the hyva-themes/magento2-theme-fallback module via Composer:

composer require hyva-themes/magento2-theme-fallback
bin/magento setup:upgrade

Luma Checkout

For documentation on using the Luma Checkout with Hyvä, refer to the Luma Checkout FAQ.

About the Theme Fallback

The theme fallback allows specific routes to use a Luma-based theme instead of Hyvä, enabling compatibility with features like the Luma Checkout.

On fallback pages, the Hyvä theme (including Tailwind CSS and Alpine.js) is inactive. Instead, RequireJS and standard Luma theme dependencies are loaded by the browser.

Consequently, any styling for pages using the theme fallback must be implemented using standard Magento Luma theme development practices, not Hyvä's.

Configuration

Configure the Luma theme fallback in the Magento admin panel under HYVA THEMES > Fallback theme > General Settings:

  1. Enable Fallback: Set to `Yes`.
    Configuration path: hyva_theme_fallback/general/enable

  2. Fallback Theme Full Path: Specify the full path to the Luma-based theme.
    Configuration path: hyva_theme_fallback/general/theme_full_path
    Default: frontend/Magento/luma

  3. List of URL Parts: Enter URL parts (one per line) that should trigger the Luma theme fallback.
    Configuration path: hyva_theme_fallback/general/list_part_of_url
    For Luma checkout, use the default paths: checkout/index, paypal/express/review, and paypal/express/saveShippingMethod (these are provided by the Hyva_LumaCheckout module).

History

Initially, the Hyva_LumaCheckout module provided fallback only for the checkout. The Hyva_ThemeFallback module was later introduced to enable theme fallback on arbitrary routes.

How It Works

The module implements a before-plugin on all frontend controllers. This plugin checks if the current route/controller/action or SEO-friendly URL path matches a configured pattern. If a match is found, the fallback theme is applied.

The theme fallback is applied under two conditions:

  1. The current route/controller/action request path matches a configured URL pattern.

    • Example: If the configured URL is customer/account, the fallback applies to all requests like customer/account/*.

    • Example: If the configured URL is customer/account/login, the fallback applies only to the login page.

  2. A part of the current request path matches the configuration.

    • Example: If the configured value is demo-product.html, the fallback applies to all pages containing demo-product.html in their path.