Skip to content

Upgrading to 1.4.0 (Beta)

We're excited to announce Hyvä version 1.4.0 (Beta)! This release modernizes our frontend with Tailwind v4 and Design Tokens, enhances HTML structures, and improves the UI. BFCache is now natively supported, and formerly experimental features like Speculation Rules and View Transitions are now standard.

When updating the Hyvä Theme to version 1.4.0, please always update the hyva-themes/magento2-theme-module to the latest version.

Even if not updating the Default Theme to 1.4.0, it is safe to update the Hyva_Theme module to the latest version (package hyva-themes/magento2-theme-module).

Notable news

Please refer to the changelogs for details about the bugfixes.

Easier Styling and Future-Proofing

Version 1.4 introduces significant improvements to our styling workflow, making it easier to customize your theme while preparing for future advancements.

Tailwind v4 and Simplified Build Process

With Tailwind CSS v4 support now integrated into the Hyvä UI library, we are bringing this future-ready capability to the Default Theme itself. We are confident this will work with most existing themes and modules but the syntax has changed a lot, so if you not sure where to start then please check the new Migrating to Tailwind 4 Docs to get you started.

This version also simplifies the Node.js build process. We now use a custom collection of Node scripts to handle parent theme and module CSS merging, reducing the complexity of building your styles.

Checkout support not there yet

Hyvä Checkout is not Tailwind 4 ready but is coming soon, until that time you need to exclude the checkout using the new hyva.config.json and add the following into you CSS: 

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

Design Tokens

We've added support for Design Tokens, which allow you to use a design system (like Figma) as the single source of truth for style values like colors, spacing, and fonts. This works similarly to how you previously used the tailwind.config.js file, but with enhanced support for integrating with professional design systems.

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

CSS Components

This release introduces CSS Components, which make it easier to adjust the theme's appearance without altering the HTML structure. Combined with Design Tokens, this approach significantly reduces the need for template overrides when creating a custom theme. This feature is a work in progress, and we plan to expand it further.

Reworked Tailwind CSS Folder Structure

To align with the upcoming Tailwind CSS v4, we've reorganized our CSS source folders.

The new structure is named after Tailwind's @layer directives: base, components, and utilities. This provides a more logical and intuitive organization.

Please see the CSS files documentation for a complete overview of the new structure.

Bfcache Support Added

Hyvä now supports the browser's back/forward cache (bfcache) to provide instant back-and-forth page loads. This feature is disabled by default to ensure backward compatibility.

To enable bfcache, two things are required:

  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.

Varnish/Fastly Prerequisite

At the time of writing, Magento 2 does not support bfcache and sends a no-store header that disables it. While the community is working on a core solution (see the open issue on the Magento 2 repo), a workaround is necessary.

We provide a patch to remove this header from the default Magento 2 Varnish configuration. This should only be applied if you understand the implications.

For complete instructions on enabling bfcache in your theme and applying the Varnish patch, please see our dedicated bfcache documentation.

Speculation Rules & View Transitions Promoted

Previously experimental features, Speculation Rules and View Transitions, are now stable and fully integrated into the theme.

Speculation Rules

The Speculation Rules API is now fully integrated into the Theme module and can be configured to your needs. It is enabled by default using prefetch instead of prerender to avoid issues with analytics tools.

We have also resolved a bug where the minicart would not update correctly on a prerendered page after an item was added via AJAX (e.g., using the Hyvä UI Ajax ATC Component), preventing out-of-sync issues.

View Transitions

View Transitions are now a core, CSS-based feature of the theme. If you wish to disable this feature, you can do so by removing the corresponding import from your CSS.

Introducing New Sliders and Carousels

As showcased in the first Hyvä Bytes, the new Snap Slider is now part of Hyvä and no longer exclusive to Hyvä UI.

This AlpineJS plugin is inspired by modern CSS-only carousels. For more information, see the Chrome Dev Blog post on CSS-only Carousels.

To ensure broad browser support while using modern techniques, we've built a progressively enhanced CSS carousel. This allows you to build a CSS-only slider and then use a small amount of JavaScript to add features like navigation buttons, a pager, and making non-visible slides inert for better performance and accessibility.

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

This upgrade also resolves many issues found in the Magento PageBuilder Slider, which used the older Glider JS library. From v1.4, all sliders in Hyvä are powered by a single Alpine plugin that can be used with simple markup:

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

The new Snap Slider follows the ARIA Authoring Practices Guide (APG). While the slider attempts to add correct roles and ARIA attributes where they are missing, you should still write semantic HTML for the best results.

If you prefer the older Page Builder Slider

If you want to continue using the previous Page Builder slider, you'll need to copy the following files into your own theme before updating:

  • vendor/hyva-themes/magento2-default-theme/web/tailwind/components/page-builder.css
  • vendor/hyva-themes/magento2-default-theme/web/tailwind/components/slider.css
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/web/js/glider.js
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/web/js/glider.min.js
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/templates/carousel-nav.phtml
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/templates/widgets/parallax.phtml
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/templates/widgets/carousel.phtml
  • vendor/hyva-themes/magento2-default-theme/Magento_PageBuilder/templates/catalog/product/widget/content/carousel.phtml

With this change, we are also introducing a new CSS component to make styling easier. The slider.css file now contains the styles for all sliders used by Hyvä. To customize sliders to match your brand, you only need to modify this one CSS file to affect all sliders.

We are also replacing the ViewModel slider with a simpler, XML-based one. This follows the same method as the product slider, allowing you to create a slider with just a small snippet of XML:

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

This slider uses the same XML arguments and requires no extra input other than passing it child blocks. Each direct child block will be treated as a slide.

It's that simple.

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

With this release, we are replacing our custom modal implementation with a new one based on the native HTML <dialog> element. This modern approach offers better performance, improved accessibility, and a more streamlined developer experience.

This change also introduces a new AlpineJS plugin, x-htmldialog, which simplifies the creation of modals and off-canvas elements.

The new implementation resolves many issues from the previous version and reduces the amount of JavaScript needed. From v1.4 onwards, all modals and off-canvases in Hyvä are powered by this single Alpine plugin, which can be used 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>

The new dialogs follow the ARIA Authoring Practices Guide (APG) for dialogs, ensuring they are accessible out of the box.

We are not yet replacing the existing ViewModel-based modals, which will continue to function as before. However, we plan to integrate them with the new HTML <dialog> element in a future release.

Changelogs

Changelogs are available from the CHANGELOG.md in the codebase, or here:

Tooling

Please refer to the Hyvä Theme upgrade docs for helpful information on how to upgrade.