Image Gallery Placement
Shows video thumbnails alongside your product images so customers can watch a video the same way they flip through product photos.
Available since v3.0.0
Overview
Image Gallery Placement inserts each product video as a thumbnail directly inside the product's image gallery — next to the regular product photos. Clicking (or hovering over) a video thumbnail replaces the main product image with an embedded video player. When the customer clicks a regular photo thumbnail, the player closes and the selected image takes over again.
This is the most natural integration point for most themes. Customers do not need to scroll down or find a separate section — video is right there in the image strip. Combined with the Video as Cover option, you can make the video play automatically the moment someone lands on the product page.
All settings in this section are independent of the other display locations (Side Panel, Tabs, Product Listings). You can enable any combination of placements simultaneously.
Configuration
- Go to Modules > Module Manager, find Product Video, and click Configure.
- Open the Image Gallery tab.
Display
| Setting | Values | Default | Description |
|---|---|---|---|
| Show Video along with the images | Enabled / Disabled | Enabled | Master switch for this placement. When disabled, no video thumbnails appear in the image gallery, regardless of other settings here. |
| Display on | All devices / Desktop only / Mobile & Tablet only | All devices | Limits this placement to a specific device type. Useful if your theme renders differently on mobile and the gallery breaks on small screens. |
Video as Cover
| Setting | Values | Default | Description |
|---|---|---|---|
Use Video as default image (Video as Cover) (PV_DEFAULT) | Enabled / Disabled | Enabled | Automatically activates the first video when the product page loads, replacing the main product photo with the video player. No click needed from the customer. |
Only set the default video once (PV_DEFAULT_ONCE) | Enabled / Disabled | Disabled | When enabled, the cover video is set only on first load. Changing a combination or triggering a page refresh does not re-fire the video cover. Useful when you want the first impression to be the video but do not want it restarting every time the customer tweaks a size or color. |
Enabling Video as Cover together with Autoplay (configured per provider in the YouTube, Vimeo, or HTML5 sections) creates a cinema-style product page: the video starts playing automatically the moment the page opens.
Thumbnail Position
| Setting | Values | Default | Description |
|---|---|---|---|
Thumbnails position (PV_THUMB_POS) | Before / After / Custom | Before | Where video thumbnails are inserted in the image strip. Before places them ahead of all product photos; After appends them at the end; Custom lets you specify an exact position number. |
Custom Thumbnails position (PV_THUMB_POS_CUSTOM) | 1, 2, 3… | 1 | Only visible when Custom is selected above. 1 = first slot, 2 = second slot, and so on. If the product has fewer images than the number you enter, the video is placed last. |
Maximum number of videos to display (PV_LIMIT) | 0 (all), or a positive integer | 0 | Caps how many video thumbnails appear in the gallery. Set to 0 to show every video. Set to 1 or 2 to prevent the gallery from overflowing when a product has many videos. |
Allow Video Repeat (PV_IMG_REPEAT) | Enabled / Disabled | Enabled | When a video limit is active, this controls whether the same video URL can also appear in other placements (Side Panel, Tabs). Disable it to make sure the same video never shows in two places on the same page. |
Thumbnail Appearance
| Setting | Values | Default | Description |
|---|---|---|---|
Custom thumbnails size (PV_CUST_THUMB_TYPE) | Any image type defined in your theme (e.g. cart, small_default) | cart | The image size preset the module uses for video thumbnail frames. Match this to what your theme uses for gallery thumbnails to ensure consistent sizing. |
Use JS to force thumbnails size (PV_FORCE_THUMB_SIZE) | Enabled / Disabled | Disabled | Forces all video thumbnails to match the exact pixel dimensions of adjacent image thumbnails via JavaScript. Enable this if video thumbnails appear larger or smaller than product image thumbnails. |
Product's image size (PV_IMG_SIZE) | Any image type in your theme, or blank for theme default | Blank (theme default) | The image size preset used for the main product image area where the video replaces the cover. Match it to your theme's primary product image size. Leave blank unless you experience sizing issues. |
Thumbnail Activation
| Setting | Values | Default | Description |
|---|---|---|---|
Thumbnail Behaviour — Desktop (PV_DESKT_BV) | Mouse Over / Click | Mouse Over (PS 1.7+), Click (PS 1.6) | Whether the video loads when the customer hovers over the thumbnail or only when they click it. Set to Mouse Over if your theme activates regular product images on hover; set to Click if your theme requires a click. |
Thumbnail Behaviour — Mobile / Tablet (PV_MOBILE_BV) | Mouse Over / Click | Click | Same as above but for touch screens. On touch devices, hover events are unreliable, so Click is almost always the correct choice. |
How It Works
When a customer opens a product page:
- The module inserts video thumbnails into the gallery strip alongside the product's existing photos.
- Each thumbnail shows a still frame pulled from YouTube or Vimeo (or a custom thumbnail for HTML5 videos) with a play icon overlay.
- When the customer hovers over or clicks a video thumbnail — depending on your Thumbnail Behaviour setting — the main product image is swapped out for an embedded video player.
- If Video as Cover is enabled, the first video loads automatically without any interaction.
- When the customer clicks a different image thumbnail, the player is removed and the selected image is displayed normally.
The gallery flow feels identical to switching between product photos — video is just another thumbnail in the strip.
Combination Changes
When a customer switches a product combination (for example, selecting a different color or size), PrestaShop reloads the image gallery via AJAX. The module detects this update and re-inserts the correct video thumbnails for the newly selected combination. If videos are assigned per-combination, only the videos for that combination appear.
If video thumbnails disappear after a customer changes a combination, increase the AJAX / Combination change refresh delay in the Theme Compatibility section of the module configuration.
Video as Cover with Combinations
If Video as Cover is enabled and Only set the default video once is disabled, the first video for the newly selected combination activates automatically after each combination change. Enable Only set the default video once to prevent this re-triggering when you want the video to play only on the initial page load.
Usage Examples
Example: Product page that leads with video
You sell a kitchen appliance and want the demo video to be the first thing customers see. Enable Video as Cover and set Autoplay to on in the YouTube settings. The video starts playing silently (or with sound, depending on your autoplay settings) the moment the page loads — no scroll, no click needed.
Example: Multiple videos without gallery overload
A product has five videos (unboxing, tutorial, three color variants). Set Maximum number of videos to display to 2 so only the two most important videos appear in the gallery. The remaining three are still accessible via the Side Panel or Tabs placement if those are enabled.
Example: Click-only gallery to match a boutique theme
Your theme activates product images only when clicked (common in fashion and luxury themes). Set Thumbnail Behaviour — Desktop to Click on Thumbnail. Video thumbnails then behave exactly like regular image thumbnails, keeping the experience consistent.
Important Notes
- Multi-shop: all Image Gallery settings are per-shop. Configure each shop separately via the shop selector in the Back Office header before opening the module configuration.
- Thumbnail position Custom relies on the gallery markup matching what the module expects. If your theme uses a non-standard gallery structure, "Before" or "After" are more reliable choices.
- The Video as Cover feature requires your theme's main image area to be identifiable via the CSS selectors set in Theme Compatibility. If the cover video does not load automatically, check those selectors first.
- Image size presets (e.g.
cart,small_default) are defined by PrestaShop and your theme. You can see available sizes in Design > Image settings in the Back Office. - On PS 1.6, Thumbnail Behaviour — Desktop defaults to Click because PS 1.6 gallery scripts handle mouse events differently.
Troubleshooting
| Problem | Solution |
|---|---|
| Video thumbnail appears much larger or smaller than product photos | Change Custom thumbnails size to the image type your theme actually uses for gallery thumbnails (often small_default on PS 1.7+ themes). Enable Use JS to force thumbnails size as a fallback. |
| Video does not load automatically on page open | Verify Use Video as default image is enabled. Then check Theme Compatibility to confirm the CSS selector for the main product image holder is correct. |
| Video restarts every time the customer changes a combination | Enable Only set the default video once to prevent the cover video from re-triggering on combination switches. |
| Video thumbnail appears in the wrong slot | Set Thumbnails position to Custom and enter the exact slot number. If the position is still wrong, your theme may not support custom positioning — switch to Before or After. |
| Too many thumbnails in the gallery | Set Maximum number of videos to display to 1 or 2 to limit how many appear. |
| Video disappears after a combination change | Increase the AJAX / Combination change refresh delay in the Theme Compatibility section so the module waits longer before re-inserting thumbnails after the gallery reloads. |
| Same video appears both in the gallery and the side panel | Disable Allow Video Repeat to prevent the same URL from appearing in multiple placements simultaneously. |
Frequently Asked Questions
If I enable Video as Cover, will the video autoplay for every visitor, including on mobile?
Video as Cover loads the player and activates the first video, but whether the video actually autoplays (starts without a click) depends on the Autoplay setting in the YouTube, Vimeo, or HTML5 sections — and on the visitor's browser. Most browsers block autoplay with sound on mobile; muted autoplay usually works.
Can I show a different video thumbnail depending on which product combination is selected?
Yes. Assign videos to specific combinations in the product edit page. When a customer selects that combination, the module swaps in the videos assigned to it. The gallery thumbnail for the previous combination is removed and the new one appears.
Will setting a video limit here also limit videos shown in the Side Panel or Tabs sections?
No. The **Maximum number of videos to display** limit applies only to the Image Gallery placement. Side Panel and Tabs have their own display settings. The **Allow Video Repeat** toggle controls whether the same video URL can appear across multiple placements, not how many videos each placement shows.
What happens if I set the Custom Thumbnails position to 3 but the product only has one image?
The video thumbnail is placed at the end of the gallery (after the one product image), since there are not enough images to reach position 3.
Does this placement work on the product listing pages (category pages)?
No. The Image Gallery placement is for the product detail page only. For category pages, use the separate **Product Listings** feature.
My theme shows thumbnails below the main image. Will videos appear there or somewhere else?
The module injects thumbnails into whatever thumbnail container your theme uses. If videos appear in the wrong location, adjust the **Thumbnail container selector** in the **Theme Compatibility** section so the module targets the right element.
Related Features
- Side Panel — Display videos in a column next to the product description instead of in the image gallery
- Tabs & Description — Show a full-size video player below the product details in a dedicated tab
- Product Listings — Add video icons or inline players to category and search result pages
- Theme Compatibility — Configure CSS selectors for the image holder, thumbnail container, and combination change delay