Skip to content

Product Gallery - Hyvä UI

New galleries coming soon

The current galleries are built on Hyvä Theme 1.4. The next Hyvä UI release will introduce a brand new gallery built on the Hyvä Theme 1.5 PHP rendering approach, leaving behind JavaScript-driven layouts in favor of modern CSS grid and native View Transitions. Less JavaScript, smoother animations, and a leaner implementation out of the box.

The Hyvä UI Product Galleries extend or completely replace the default Hyvä Theme gallery, adding customization options that you configure through etc/view.xml.

These galleries are built to improve user experience (UX) and fix accessibility (A11Y) issues. Along the way, they also change how some gallery features behave compared to the Magento 2 Luma Fotorama gallery you may already know, so expect a few differences if you are migrating.

Hyvä UI ships several Product Gallery versions, so you can pick the one that fits your needs:

  • A - Basis:
    Adds vertical thumbnails while keeping the core functionality of the default Hyvä Theme gallery.
  • B - Fancy:
    A complete rebuild of the default Hyvä Theme gallery. It looks a lot like version A but adds extensive customization through etc/view.xml. You can enable or disable the fullscreen dialog and switch on the magnifier.
  • C - Grid:
    Built for image-heavy stores. This version lays out a grid of images and videos so users see multiple media elements at once, which is the main difference from version B.
  • D - Splide:
    Similar to version B but without thumbnails. It uses SplideJS for smooth transitions and a minimalist design.

The Hyvä UI Product Gallery is configured through a <var name="gallery"> block in your theme's etc/view.xml. The options below cover every setting available across the different gallery versions. Not every version supports every option, so always check the README.md that ships with your gallery to confirm which ones apply.

Check version compatibility first

Before using any of these options, verify that your Hyvä UI Library version supports them. Features are sometimes introduced in later releases, so keep your library up to date and consult the Hyvä UI Gallery or the release notes to confirm support for your specific version.

app/design/frontend/{Vendor}/{theme}/etc/view.xml
<var name="gallery">
    <var name="loop">false</var> <!-- Gallery navigation loop (true/false) -->
    <var name="caption">false</var> <!-- Display alt text as image title (true/false) -->
    <var name="allowfullscreen">true</var> <!-- Turn on/off fullscreen (true/false) -->
    <var name="navdir">horizontal</var> <!-- Direction of the thumbnails (horizontal/vertical) -->
    <var name="navarrows">false</var> <!-- Turn on/off the thumbnail arrows (true/false) -->

    <!-- Contains Hyvä-only options -->
    <var name="nav">thumbs</var> <!-- Gallery navigation style (false/thumbs/dots/counter) -->
    <var name="arrows">false</var> <!-- Turn on/off the gallery arrows (start/end/true/false) -->

    <!-- Hyvä-only options -->
    <var name="fullscreenicon">false</var> <!-- Turn on/off icon for allowfullscreen (true/false) -->
    <var name="navoverflow">false</var> <!-- Turn on/off overflow style (true/false) -->
    <var name="autoplay">false</var> <!-- Turn on/off autoplay for videos (true/false) -->

    <var name="magnifier">
        <var name="enable">false</var> <!-- Turn on/off magnifier (true/false) -->
        <var name="zoom">80</var> <!-- Magnifier zoom level (integer) -->
        <var name="fullscreen">true</var> <!-- Turn on/off magnifier when viewing fullscreen (true/false) -->
        <var name="trigger">click</var> <!-- How to show the magnifier (hover/click) -->
    </var>
</var>

The sections below highlight the options that behave differently from what you might expect, along with the trade-offs to keep in mind.

The gallery magnifier zooms into a product image on hover or click, controlled by the <var name="magnifier"> block. People often expect it to work similarly to the Luma theme version, but the Hyvä UI implementation makes some deliberate choices.

The magnifier only works on non-touch devices. On touch-enabled devices, it's recommended to use the native pinch-to-zoom gesture, which gives users a better experience.

Why isn't the magnifier available on mobile?

  1. Performance: Supporting touch-based magnification needs extra JavaScript to avoid clashing with native touch interactions like swiping. That adds complexity and page load weight for little gain.
  2. Conflict prevention: Custom zoom gestures can interfere with native touch gestures such as swiping, which leads to a frustrating experience.

Autoplay for Videos

The autoplay option plays every video in the gallery, not just the first one. When enabled, autoplay skips the video preview and plays the active video automatically.

Autoplay is not available in Gallery C, since that version displays all items at the same time.

Autoplay affects performance

Video data loads as soon as a video becomes the active gallery item. Enabling autoplay can slow down your page, especially when the first gallery item is a video, because that data loads on page load.

The caption option displays the image's alt text as a title in the gallery. Turn it on when you want users to see descriptive labels alongside each image.

Add meaningful alt text to your product images before enabling captions. A caption will not display when the alt text is missing or identical to the product name.

Navigation dots are a compact alternative to thumbnails and are exclusive to Gallery D (Splide). Set them with <var name="nav">dots</var> in etc/view.xml.

Dots are hidden automatically on touch-based devices to improve accessibility, because the default touch target for dots is too small to tap reliably.

If you want to keep dots on touch devices, you can change how SplideJS renders them. For more on Gallery D options, see the README.md that ships with the gallery.