What Is Hyva Theme for Magento 2 and Why It Matters

Hyva is an alternative frontend theme for Magento 2 that replaces the default Luma theme's technology stack. Where Luma relies on RequireJS, KnockoutJS, jQuery, and LESS, Hyva uses Tailwind CSS and Alpine.js. This architectural shift results in dramatically faster page loads and a simplified development experience, but it also requires extensions to provide Hyva-compatible templates.

Hyva vs Luma Architecture

Luma (Default)

• CSS: LESS preprocessor, compiled to CSS
• JavaScript: RequireJS module loader, KnockoutJS for UI components, jQuery for DOM manipulation
• Page weight: Typically 2-4 MB of JS/CSS on first load
• Complexity: Deep abstraction layers, XML layout system with UI components

Hyva

• CSS: Tailwind CSS (utility-first, purged to only used classes)
• JavaScript: Alpine.js for reactivity, vanilla JS for utilities
• Page weight: Typically 200-400 KB of JS/CSS on first load
• Complexity: Simpler template structure, direct DOM interaction

The result is 5-10x reduction in frontend payload, which translates directly to faster page load times and better Core Web Vitals scores.

Alpine.js Version Compatibility

Hyva uses Alpine.js v3. Alpine.js v2 backward compatibility is not planned. If you are writing custom Hyva components or modifying templates, use the v3 API:

• x-data syntax changes from v2 to v3
• $el and $refs behavior differences
• Event modifiers and lifecycle hooks follow the v3 specification

Check the Alpine.js v3 documentation when developing Hyva components.

Template Override Pitfalls

When customizing Hyva templates, preserve the base Magento CSS classes that Magento's JavaScript relies on for functionality. Removing or renaming CSS classes breaks features that detect elements by class name.

For example, the block-content class on sidebar blocks is used by Magento's JavaScript to identify and process sidebar content. Removing it causes sidebar features (layered navigation, filters) to malfunction even though the visual appearance may look correct.

Best practice: When overriding a Hyva template, start from the existing Hyva template file (not the Luma template) and make minimal changes. Always test interactive features after template modifications.

Clearing Static Content After Template Changes

After modifying templates, clear the static content cache to see changes:

rm -rf pub/static/* var/view_preprocessed/*
php bin/magento cache:flush

In developer mode, Magento regenerates static content on demand. In production mode, you must redeploy static content after any template change.

Hyva CMS and PageBuilder Support

Hyva CMS (version 1.0.2+) provides compatibility with Adobe's PageBuilder. If you are migrating from Luma to Hyva and your CMS pages use PageBuilder content, ensure you are running Hyva CMS 1.0.2 or later. Earlier versions do not render PageBuilder widgets correctly.

Extension Compatibility

This is the most significant consideration when adopting Hyva. Magento extensions that include frontend templates, JavaScript, or CSS typically ship Luma-compatible assets. These do not work with Hyva out of the box.

Compatibility Modules

Extension vendors provide dedicated Hyva compatibility modules that replace the Luma frontend assets with Hyva-compatible versions. These are separate Composer packages installed alongside the base extension.

Check the Hyva Compatibility Module Tracker for extension compatibility status.

See also: Hyva Compatibility Modules: Install

What Requires a Compatibility Module

• Any extension that renders frontend UI elements (product pages, category pages, checkout steps)
• Extensions using RequireJS modules
• Extensions with KnockoutJS UI components
• Extensions with LESS/CSS that depends on Luma's style structure

What Does NOT Require a Compatibility Module

• Backend-only extensions (admin panel features, cron jobs, API)
• Extensions that only add backend logic (price rules, import/export, indexers)
• Extensions that use only standard Magento XML layout with no custom JS/CSS

Licensing

Hyva is a commercial product with a per-project license. Each Magento installation requires its own Hyva license. Evaluate the cost against the performance and development benefits for your specific project.