Upgrading to 1.4.0

Hyvä 1.4.0 is here, bringing a modernized frontend with Tailwind v4, Design Tokens, enhanced HTML, and improved UI. It natively supports BFCache, and previously experimental features like Speculation Rules and View Transitions are now enabled by default.

Always update hyva-themes/magento2-theme-module to the latest version when upgrading to Hyvä Theme 1.4.0.

It's safe to update the Hyva_Theme module (package hyva-themes/magento2-theme-module) to the latest version, even if you're not updating the Default Theme to 1.4.0.

Refer to the changelogs for bugfix details.

Notable news

Replacing hyva-themes/magento2-reset-theme with hyva-themes/magento2-base-layout-reset

The new hyva-themes/magento2-base-layout-reset module replaces hyva-themes/magento2-reset-theme, improving TTFB for cold layout cache requests. It dynamically generates layout instructions without block declarations, eliminating the need for a separate reset theme. Benefits include:

1. Fewer layout XML files to load and process, saving time on requests hitting a cold layout cache.
2. More future-proof because new core Magento modules will be automatically included in the reset.

The generated base layout reset is backward compatible.

Existing themes extending from the reset-theme will still work if hyva-themes/magento2-reset-theme remains installed. If the upgrade removes it (e.g., as a transitive dependency), you'll need to explicitly reinstall it until your custom Hyvä base themes migrate to the generated base layout reset.

This migration is optional; you can continue using themes that extend from the reset-theme. For migration steps and tooling, see the generated base layout docs.

Easier Styling and Future-Proofing

Version 1.4 significantly improves styling, simplifying theme customization and preparing for future advancements.

Tailwind v4 and Simplified Build Process

Tailwind CSS v4 support, already in Hyvä UI, is now integrated into the Default Theme. While generally compatible, the syntax has changed significantly. If you need guidance, refer to the new Updating to Tailwind 4 docs.

The Node.js build process is simplified, using custom Node scripts for parent theme and module CSS merging, which reduces styling build complexity.

Hyvä Checkout v1.3.6+ and Hyvä CMS v1.0.2+ support Tailwind 4 and work without manual adjustments.

For Tailwind v4 warnings like Unknown at rule: @screen, see the TailwindCSS Troubleshooting → Unknown at rule: @screen FAQ.

@source "../../../../../../../vendor/hyva-themes/magento2-hyva-checkout/src/**/*.phtml";
@source "../../../../../../../vendor/hyva-themes/magento2-hyva-checkout/src/**/*.xml";

Design Tokens

Design Tokens are now supported, enabling design systems (e.g., Figma) as the single source of truth for style values like colors, spacing, and fonts. This functions similarly to tailwind.config.js, but with enhanced integration for professional design systems.

For more information, see the documentation on what Design Tokens are and our Node script for tokens.

CSS Components

CSS Components are introduced, simplifying theme appearance adjustments without HTML changes. Combined with Design Tokens, this reduces template overrides for custom themes. This feature is a work in progress and will be expanded.

Reworked Tailwind CSS Folder Structure

Our CSS source folders are reorganized to align with Tailwind CSS v4.

The new structure, named after Tailwind's @layer directives (base, components, utilities), offers a more logical organization.

See the CSS files documentation for a complete overview.

Bfcache Support Added

Hyvä now supports browser back/forward cache (bfcache) for instant page loads. It's disabled by default for backward compatibility.

Enabling bfcache requires two steps:

1. Default Theme Adjustments Support for bfcache is included automatically in version 1.4.0. If you are using an older version, you will need to make manual adjustments.

2. Varnish/Fastly Configuration A manual configuration change is required for stores using Varnish or Fastly. By default, Magento 2 prevents bfcache from working.

For full instructions on enabling bfcache and applying the Varnish patch, see our dedicated bfcache documentation.

Speculation Rules & View Transitions Promoted

Speculation Rules and View Transitions, previously experimental, are now stable and fully integrated.

Speculation Rules

The Speculation Rules API is now fully integrated and configurable in the Theme module. It defaults to prefetch (instead of prerender) to prevent analytics issues.

A bug where the minicart wouldn't update correctly on prerendered pages after AJAX item additions (e.g., Hyvä UI Ajax ATC Component) has been resolved, preventing out-of-sync issues.

View Transitions

View Transitions are now a core, CSS-based theme feature. Disable it by removing the corresponding CSS import.

Introducing New Sliders and Carousels

The new Snap Slider, showcased in the first Hyvä Bytes, is now a core Hyvä feature, no longer exclusive to Hyvä UI.

This AlpineJS plugin draws inspiration from modern CSS-only carousels. See the Chrome Dev Blog post on CSS-only Carousels for more.

We've built a progressively enhanced CSS carousel for broad browser support with modern techniques. This enables CSS-only sliders, augmented with minimal JavaScript for navigation, pagers, and making non-visible slides inert, improving performance and accessibility.

This makes the carousel more robust and accessible than most JavaScript-based alternatives.

This upgrade fixes many issues in the Magento PageBuilder Slider (which used Glider JS). From v1.4, all Hyvä sliders use a single Alpine plugin with simple markup:

<section x-data x-snap-slider>
    <div data-track>
        <!-- Slides go here -->
    </div>
</section>

The new Snap Slider follows ARIA APG. While it adds missing roles and ARIA attributes, semantic HTML is still recommended for best results.

A new CSS component simplifies slider styling. The slider.css file now centralizes styles for all Hyvä sliders, allowing you to customize all sliders by modifying this single file.

The ViewModel slider is replaced with a simpler, XML-based version, mirroring the product slider. Create a slider with a small XML snippet:

<block name="block-slider" template="Hyva_Theme::elements/slider.phtml">
    <!-- Your Slides -->
</block>

This slider uses the same XML arguments and only requires child blocks, where each direct child becomes a slide.

It's that simple.

Introducing New Modals and Off-canvases using the native HTML Dialog

This release replaces our custom modal implementation with a new one based on the native HTML <dialog> element, offering better performance, improved accessibility, and a streamlined developer experience.

A new AlpineJS plugin, x-htmldialog, is introduced to simplify modal and off-canvas creation.

The new implementation resolves previous issues and reduces JavaScript. From v1.4, all Hyvä modals and off-canvases use this single Alpine plugin with simple, semantic markup:

<div x-data="{ open: false }">
    <button class="btn" @click="open = true">
        Open Dialog
    </button>

    <dialog x-htmldialog="open = false">
        <h3 class="text-lg font-medium">Dialog Title</h3>
        <p>This is the content of the dialog.</p>
        <button class="btn" @click="open = false">
            Close
        </button>
    </dialog>
</div>

New dialogs follow ARIA APG, ensuring out-of-the-box accessibility.

Existing ViewModel-based modals remain functional but will be integrated with the new HTML <dialog> element in a future release.

Breaking change regarding Adobe Cloud deployments

Tailwind v4 merging is incompatible with Adobe Cloud's default .gitignore, as its @source feature ignores listed files. To fix this, use a .gitignore that explicitly lists files and directories to ignore, instead of an ignore-all-then-unignore approach.

Refer to our Adobe Commerce Cloud Deployment for more details.

Changelogs

Changelogs are available in CHANGELOG.md or here:

• Changelog Default Theme
• Changelog Theme Module
• Changelog Default CSP Theme

Tooling

Refer to the Hyvä Theme upgrade docs for upgrade information.