Custom Product Image Gallery for Magento 2

What you get

Magento 2 Product Gallery

Panth Product Gallery replaces the default image gallery on the Magento 2 product detail page with a gallery that is configured from the admin. It offers horizontal, vertical and grid thumbnail layouts, inner zoom on hover, a fullscreen lightbox with an image counter and keyboard navigation, and prev/next arrows on the main image. When the module is enabled, a plugin on Magento\Catalog\Block\Product\View\Gallery swaps the output of the standard gallery block for the module's own template; when it is disabled, Magento renders its default gallery again.

The module is aimed at merchants who want a different gallery layout on the product page without theme work. It ships two templates: one for Hyva (Alpine.js and Tailwind CSS) and one for Luma (vanilla JavaScript). The active theme is detected through Panth_Core and the matching template is selected automatically.

Product page: kishansavaliya.com/magento-2-productgallery.html

Features

• Three thumbnail layouts selectable in the admin: "Horizontal Thumbnails (Below Main Image)", "Vertical Thumbnails (Left of Main Image)" and "Grid (All Images Visible)".
• Inner zoom on hover over the main image (3x by default); the Luma template preloads the large image on first hover, the Hyva template shows the large image in a positioned overlay.
• Fullscreen lightbox opened by clicking the main image (or a grid item on Hyva), with prev/next controls, an optional "1 / 5" style image counter, zoom in/out buttons and mouse-wheel zoom.
• Optional keyboard navigation in the lightbox: arrow keys to move between images, Escape to close, "+" and "-" to zoom (the Hyva template also resets zoom with "0").
• Optional prev/next arrows on the main image and an optional infinite loop from the last image back to the first.
• Optional touch swipe on the main image in both templates (a left or right swipe of more than 50 px changes the image).
• The gallery opens on the product's base image.
• On Hyva, all three layouts follow configurable product option changes: the update-gallery event sent by the Hyva configurable options script replaces the images and thumbnails, and reset-gallery restores the parent product images.
• On Luma, the gallery follows configurable swatch and drop-down option changes. The gallery element carries data-gallery-role="gallery-placeholder" and exposes a small gallery API through jQuery data('gallery') (updateData, returnCurrentImages, first, last, prev, next, seek), which Magento's swatch-renderer.js and configurable.js call instead of the Fotorama gallery. The main image, thumbnails and arrows are rebuilt from the images of the selected child product, and resetting the options restores the parent images. Product videos are not shown by this gallery; when it replaces the Luma gallery, the core product video initialisation block (product.info.media.video) is not rendered.
• Disabled gallery entries are skipped and images are ordered by their media gallery position.
• Every image gets an alt attribute and a title attribute, taken from the caption and title of the core gallery images JSON (see Optional alt text integration below).
• Media gallery data is added to product collections while the module is enabled, so the images are available without a second load.
• A "Panth Product Gallery" widget is declared in etc/widget.xml for use through the Magento widget system.
• Admin settings are available at default, website and store view scope.
• Unit tests are included under Test/Unit.

Usage

On the product page, Plugin\HideDefaultGallery runs as an afterToHtml plugin on Magento\Catalog\Block\Product\View\Gallery. It acts only on the blocks named product.media (Hyva) and product.info.media.image (Luma), builds the image list for the current product, and re-renders the block with the module template. If the product has no enabled images, or rendering fails, the original gallery HTML is returned. No layout XML overrides are needed; the layout files shipped with the module are intentionally empty.

• Hyva: view/frontend/templates/hyva/gallery.phtml is used. It is an Alpine.js component (panthGallery()) with Tailwind utility classes and inline styles, plus a lightbox script that appends its overlay to document.body and exposes it as window.panthLightbox.
• Luma: view/frontend/templates/gallery.phtml is used. It is plain JavaScript and includes its own inline <style> block; RequireJS and jQuery are only used, when present, to register the gallery API with data('gallery') and trigger gallery:loaded. Additional Luma styles are in view/frontend/web/css/source/_module.less.

Layouts: the horizontal and vertical layouts show a main image with a strip of clickable thumbnails (below or on the left) and, optionally, arrows; thumbnails are only rendered when the product has more than one image. On Hyva the grid layout lists all images in a 2-column grid (3 columns from the md breakpoint) without a separate main image, and clicking a grid item opens the lightbox. On Luma the grid layout renders the same grid (2 columns on phones, 3 columns from 768 px) and rebuilds it when a swatch changes the images. Grid items are buttons when the lightbox is enabled, so they can be reached and opened with the keyboard. The vertical layout shows the thumbnail column on the left from 1024 px on Hyva and from 768 px on Luma; on narrower screens the thumbnails move below the main image. Thumbnails mark the current image with aria-current, and when a thumbnail or the main image has focus the arrow keys (plus Home and End on thumbnails) move between images. The main image is rendered by the server with its width and height attributes and fetchpriority="high", so it appears before JavaScript runs and does not shift the layout.

Zoom: while the cursor moves over the main image, the large image is shown scaled by the zoom level (3 by default) with the origin following the cursor. There is no lens or overlay zoom mode in the templates. Zoom only reacts to a mouse pointer and stops over the arrows, so taps on touch screens do not leave the image zoomed.

Lightbox: shows the large image size (product_page_image_large), the current position counter, prev/next arrows, zoom in/out buttons and a close button; clicking the backdrop closes it. On touch screens the image can be swiped left or right. The lightbox is a labelled dialog: focus moves to its close button, Tab stays inside it and focus returns to the main image on close; the main image itself opens the lightbox with Enter or Space. Keyboard handling is a keydown listener on the document that is only emitted when "Keyboard Navigation" is Yes. Escape closes the lightbox even when keyboard navigation is off, and the prev/next controls are hidden when there is only one image. The lightbox always wraps around at the ends regardless of the "Infinite Loop" setting, which only affects the main image navigation.

Templates can be overridden in a theme in the usual way by placing a copy under Panth_ProductGallery/templates/gallery.phtml or Panth_ProductGallery/templates/hyva/gallery.phtml. Both templates read their data from the block: panth_gallery_images, panth_gallery_config and panth_gallery_viewmodel (an instance of Panth\ProductGallery\ViewModel\Config), which the plugin sets before rendering.

Widget: etc/widget.xml declares the "Panth Product Gallery" widget backed by Block\Widget\Gallery, with a single "Template" parameter ("Default Gallery"). The block renders the gallery for the product currently in the catalog registry and outputs nothing when no product is loaded, so it is only useful on pages where a product is set.

Optional alt text integration: the alt and title of each image are read from getGalleryImagesJson() of the core Magento\Catalog\Block\Product\View\Gallery block (the caption and, when present, title keys). Plugin\HideDefaultGallery uses the gallery block it wraps; Block\Gallery creates a core gallery block for the current product. Any module that rewrites that JSON, for example an image SEO module with an after-plugin on getGalleryImagesJson(), therefore also changes the alt and title in this gallery. Without such a module the caption is the image label, or the product name when no label is set. If the JSON cannot be read or does not match the product's media gallery, the image label or product name is used.

Documentation

See USER_GUIDE.md. It covers installation, verifying the module is active, configuration, gallery layouts, zoom, lightbox and navigation settings, widget usage, theme customization and troubleshooting.

Changelog

See CHANGELOG.md.

Compatibility

Composer constraints for Magento packages: magento/framework ^103.0, magento/module-catalog ^104.0, magento/module-store ^101.0, magento/module-backend ^102.0, magento/module-widget ^101.0, magento/module-config ^101.0.

Requirements

• Magento Open Source or Adobe Commerce 2.4.4 to 2.4.8
• PHP 8.1 or newer
• mage2kishan/module-core ^1.0 (required; provides the "Panth Extensions" configuration tab, the admin menu parent, the theme detection helper and the theme-config view model)
• Suggested: hyva-themes/magento2-default-theme ^1.0 when the store runs on Hyva

Installation

composer require mage2kishan/module-productgallery
bin/magento module:enable Panth_Core Panth_ProductGallery
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

setup:di:compile is only needed in production mode. setup:static-content:deploy -f is listed because the module ships a LESS file under view/frontend/web/css/source/ for Luma.

Check that the module is enabled:

bin/magento module:status Panth_ProductGallery

Configuration

Go to Stores > Configuration > Panth Extensions > Product Gallery. The section is also reachable from the admin menu under Panth Extensions > Product Gallery > Configuration. All settings can be set at default, website and store view scope.

General Settings

Gallery Layout

Zoom

Lightbox

Navigation

Design & Colors

This group has no fields. It explains that gallery colours and sizes come from etc/theme-config.json, which is registered with the Panth\Core\ViewModel\ThemeConfig view model from Panth_Core. The file defines CSS variables such as --gallery-primary, --gallery-thumb-active-border, --gallery-zoom-bg, --gallery-lightbox-bg and --gallery-border-radius, which are used by the Luma LESS file.

Config paths:

• panth_productgallery/general/enabled
• panth_productgallery/layout/layout_type
• panth_productgallery/zoom/enable_zoom
• panth_productgallery/lightbox/enable_lightbox
• panth_productgallery/lightbox/show_counter
• panth_productgallery/lightbox/enable_keyboard_nav
• panth_productgallery/navigation/show_arrows
• panth_productgallery/navigation/enable_swipe
• panth_productgallery/navigation/infinite_loop

etc/config.xml also sets defaults that have no admin field and are read through Helper\Data: layout/thumb_position (bottom), layout/main_image_width and layout/main_image_height (700), layout/thumb_width and layout/thumb_height (72), layout/visible_thumbs (5), zoom/zoom_type (inner) and zoom/zoom_level (3, clamped to 2 to 5). The main image and thumbnail sizes, and the thumbnail width and height attributes, are taken from these values.

Default behaviour after installation: the module is enabled, the horizontal layout is used, zoom, lightbox, counter, keyboard navigation and arrows are on, and infinite loop is off.

Uninstallation

bin/magento module:disable Panth_ProductGallery
composer remove mage2kishan/module-productgallery
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The module creates no database tables. Values saved under panth_productgallery/* in core_config_data remain after removal and can be deleted manually if required.

License

Commercial software license. See LICENSE.txt in this repository.

Developer Notes

• Module name: Panth_ProductGallery
• Composer package: mage2kishan/module-productgallery
• Namespace: Panth\ProductGallery (PSR-4 from the module root)
• Load sequence: after Magento_Catalog, Magento_Store, Panth_Core
• Key classes:
• Plugin\HideDefaultGallery: afterToHtml plugin on Magento\Catalog\Block\Product\View\Gallery (declared in etc/frontend/di.xml, sort order 10)
• Block\Gallery: AbstractProduct block with getGalleryImages(), getGalleryConfig(), getGalleryConfigJson(), isEnabled(); getTemplate() picks the Hyva or Luma template
• Block\Widget\Gallery: widget block extending Block\Gallery
• ViewModel\Config: view model exposing all configuration getters and getGalleryConfig()
• Helper\Data: configuration reader for panth_productgallery/*
• Observer\ProductCollectionLoadAfter: observer on catalog_product_collection_load_after that calls addMediaGalleryData() on the collection while the module is enabled
• Model\Config\Source\LayoutType, ThumbPosition, ZoomType: option sources (only LayoutType is used by system.xml)
• DI: etc/frontend/di.xml registers the module with Panth\Core\ViewModel\ThemeConfig (registeredModules) so etc/theme-config.json is picked up
• ACL resource: Panth_ProductGallery::config ("Panth Product Gallery Configuration") under Magento_Config::config
• Admin menu: Panth_ProductGallery::group ("Product Gallery") and Panth_ProductGallery::settings ("Configuration") under Panth_Core::panth_extensions
• No database tables, controllers, routes, web API endpoints, console commands or cron jobs are defined
• Translations: i18n/en_US.csv