PrestaShop Product Gallery — Complete Guide

Overview

PrestaShop Product Gallery (module folder dfgallerypro) replaces the native product page image gallery with a modern one: high resolution inner zoom on hover, vertical or horizontal thumbnails, a fullscreen viewer with pinch on mobile, image filtering by selected combination, and a loading strategy optimized for the Largest Contentful Paint.

The module overrides no template: the gallery is mounted with JavaScript in place of the native image block, which is hidden. It uses no SQL table, no override, and its JavaScript is written in vanilla JS, without jQuery.

Installation

Requirements

• PrestaShop 8.0 to 9.x
• PHP 7.4 or higher
• A theme based on the classic theme (or exposing the standard product page image containers)

Install the module

1. In the back office, open Modules → Module Manager.
2. Click Upload a module and select the dfgallerypro.zip archive.
3. Once installed, click Configure.

Configuration

All settings live on the module configuration screen. Changes take effect immediately on the storefront, with no cache clearing required.

Thumbnails position

• Left (vertical) — thumbnail column to the left of the main image. This is the default.
• Right (vertical) — column to the right of the main image.
• Bottom (horizontal) — horizontal strip below the main image.

Zoom mode and zoom level

• Hover (inner zoom) — the zoom follows the cursor inside the image. Active only on devices with a fine pointer (desktops), detected automatically.
• Click (opens fullscreen) — no hover zoom; a click opens the fullscreen viewer.
• Disabled — no zoom interaction on the stage.

The zoom level defines the magnification factor of the hover zoom, from 1.5 to 4. The recommended value is between 2 and 3.

Fullscreen viewer and pinch

When the fullscreen viewer is enabled, clicking the main image (or the expand button in the bottom-right corner) opens an immersive viewer on a dark backdrop: image counter, arrows, closing via the Escape key or a click on the backdrop.

The Pinch to zoom on mobile option enables, inside this viewer, two finger pinch (up to 4x), double tap to zoom in and out, and dragging the zoomed image. On desktop, the mouse wheel zooms.

Image filtering by combination

• Strict — only the images associated with the selected combination are shown.
• Smart (recommended) — combination images come first, followed by the other product images.
• Disabled — all images are always shown.

Lazy loading and LCP preload

• Lazy loading — only the first image loads eagerly; thumbnails beyond the fourth and subsequent images load lazily. Neighbor images are prefetched on every navigation for instant transitions.
• Preload cover image (LCP) — adds a high priority preload hint for the cover image in the page head, improving the product page Largest Contentful Paint.
• Show navigation arrows — displays previous / next arrows on the main image (visible on hover on desktop, always visible on mobile).

Associating images with combinations

Variant filtering relies on native PrestaShop associations, with no extra configuration in the module:

1. Open the product page in the back office, Combinations tab.
2. Open each combination and tick its matching images in the Images section.
3. Save: the gallery uses these associations immediately on the storefront.

How it behaves on the storefront

On desktop

• Hovering the image: inner zoom following the cursor (when hover mode is active).
• Clicking the image or the expand button: opens the fullscreen viewer.
• Keyboard arrows to navigate, Escape to close, mouse wheel to zoom inside the viewer.

On mobile

• Horizontal swipe on the main image to move between images.
• Tapping the image: opens fullscreen.
• Inside fullscreen: two finger pinch, double tap, swipe to navigate, position counter.

Performance and LCP

The module is built to improve the product page Core Web Vitals rather than degrade them:

• The cover image is announced as a high priority preload in the page head (optional).
• The first stage image loads with high fetch priority and asynchronous decoding.
• Thumbnails use native browser lazy loading; the original image used for zoom only loads on first hover.
• The JavaScript loads at the bottom of the page, with no external dependency.

Theme compatibility and troubleshooting

The module targets the standard image containers of classic-based themes. If your theme uses a completely different structure, the native gallery simply remains displayed, with no error.

• The gallery does not show — check that your theme exposes a standard image container on the product page. Contact our support with a product page URL: adapting to a specific theme is usually quick.
• The zoom looks blurry — zoom sharpness depends on the resolution of the uploaded source images. Upload images at least 1500 px wide for best results.
• Filtering does not react to variant changes — check that images are associated with combinations in the Combinations tab of the product page, and that the filtering mode is not set to Disabled.
• Quick view — the quick view modal deliberately keeps the native gallery to avoid any interference with core JavaScript.

Uninstallation

Uninstalling from the module manager removes all module configuration keys. No residual data remains: the module created no table, no override, and no file outside its own folder.

Changelog

• 1.0.0 (2026-07-16) — Initial release: HD hover zoom based on the original image, fullscreen viewer with pinch, image filtering by combination (strict / smart), LCP preload, lazy loading, vertical or horizontal thumbnails, FR, EN, ES, DE, IT translations.