Theme Compatibility
Tells the module exactly where your theme's image gallery elements are located so videos appear in the right place and play correctly alongside your theme's slider.
Available since v3.0.0
Overview
Product Video works out of the box on the default PrestaShop Classic theme. When you use a custom or third-party theme, the module may not find the image gallery, thumbnail strip, or main image container because those themes use different CSS class names and HTML structures. The Theme Compatibility section is where you describe your theme's structure to the module.
You should visit this section if videos do not appear in the image gallery, thumbnails are mispositioned, videos do not load when clicking a thumbnail, or the video conflicts with your theme's image slider. Most problems are resolved by selecting the correct Theme Preset and, if needed, fine-tuning a few individual selectors.
The section is split into subsections: Core Selectors (the three essential selectors), Slider Configuration (for themes using a gallery slider library), Thumbnail and Image Markup (HTML structure adjustments), Debug, and More Options (timing, interaction, and edge-case tweaks).
Configuration
Go to Modules > Module Manager > Product Video > Configure, then click the Theme Compatibility tab.
Theme Preset
Select your PrestaShop version to auto-fill all core selector fields with known-correct values for that version's default theme. After selecting a preset, review the populated values and click Save.
| Option | Description |
|---|---|
| Custom (manual) | All selector fields stay as-is; you fill them in yourself |
| PrestaShop 1.6 | Fills selectors for the default PS 1.6 theme |
| PrestaShop 1.7 Classic | Fills selectors for the PS 1.7 Classic theme |
| PrestaShop 8 | Fills selectors for the PS 8 default theme |
| PrestaShop 9 | Fills selectors for the PS 9 default theme |
Start here. Select your PS version's preset, save, and test on a product page before changing anything else. This resolves the majority of theme integration issues with no additional configuration.
Core Selectors
These three selectors are the most critical. If videos do not appear in the image gallery at all, these are the first fields to check.
| Field | PS 1.6 default | PS 1.7 / 8 / 9 default | Description |
|---|---|---|---|
| Product main image | #bigpic | .product-cover:eq(0) img:eq(0) | Selector for the <img> element of the main product photo. The video iframe replaces this image. |
| Product main image container / Video Placeholder | #view_full_size | .product-cover:eq(0) | Selector for the container around the main image. The video embed is sized and positioned within this element. |
| Selector for Thumbnails Container | #thumbs_list_frame | .product-images:eq(0) | Selector for the <ul> or wrapper element that holds all product image thumbnails. Video thumbnails are injected into this container. |
All selectors use standard jQuery syntax: .classname for classes, #id for IDs, :eq(0) to target the first match on the page. Open your browser developer tools (F12, Inspector tab) on any product page to find the correct selectors for your theme.
List and Interaction Settings
| Field | Options | Default | Description |
|---|---|---|---|
| List type | li, div, a | li | The HTML element used for each thumbnail item in your theme's thumbnail list. |
| Click Behaviour Type | mousedown, mouseup, click, tap | mousedown | The jQuery event used to detect thumbnail clicks. Change this if thumbnails do not respond, or only respond on the second click. |
Slider Configuration
If your theme uses an image slider library for the product gallery, you must tell the module which one so it can insert video thumbnails into the slider correctly.
| Field | Options / Notes | Default | Description |
|---|---|---|---|
| Custom Image Slider | Slick Slider, BX Slider, Owl Carousel (pre-2.0), Owl Carrousel, Swiper Slider, Flickity Carousel, Light Slider, Bootstrap 5 Carousel | None | Select your theme's slider library. |
| Selector for the slider's thumbnails container | jQuery selector | — | The element wrapping the thumbnail track inside the slider. Example: for Swiper, point to the element with .swiper-container. |
| Selector for the main image's slider | jQuery selector | — | The slider element wrapping the main product image. Fill this in if your theme builds a slider for the main image area. |
| Main image's slider HTML (before) | Raw HTML | — | HTML inserted before each image slide. Use if your slider library requires a specific wrapper tag per slide. |
| Main image's slider HTML (after) | Raw HTML | — | HTML inserted after each image slide. |
| Sync thumbnail and image sliders | Enabled / Disabled | Disabled | Enable only if your theme's thumbnail slider and main image slider are synchronized. |
| Refresh slider after adding the items | Enabled / Disabled | Disabled | Forces the slider to reinitialize after video thumbnails are injected. Enable if using Slick Slider or Owl Carousel v2 and video thumbnails are not visible. |
Thumbnail and Image Markup
Use these fields when your theme wraps thumbnails in specific HTML that the module must replicate around the video thumbnails it injects.
| Field | Default | Description |
|---|---|---|
| Additional class(es) for Thumbnail Items | — | CSS classes added to each injected video thumbnail item. Separate multiple classes with spaces. |
| Before Thumbnail | — | Raw HTML inserted before each thumbnail element. |
| After Thumbnail | — | Raw HTML inserted after each thumbnail element. |
Thumbnail link <a> | Disabled | Enable if your theme wraps each thumbnail item in an <a> tag. The module will generate a matching link wrapper around the video thumbnail. |
Additional classes for <a> link tag | — | CSS classes for the generated link element. Space-separated. |
| Additional class for IMG tag | — | CSS class added to the video thumbnail <img> element. |
Debug
| Field | Default | Description |
|---|---|---|
| Debug video generation in browser console | Disabled | Outputs detailed initialization and injection logs to the browser console. Use when diagnosing integration problems. Disable in production. |
More Options
These settings address specific edge cases in certain themes. Leave them at their defaults unless you have a specific problem they are meant to solve.
| Field | Default | Description |
|---|---|---|
| Load delay | 0 ms | Milliseconds to wait before the module initializes. Increase on heavy JavaScript themes that finish rendering after the standard DOM-ready event. |
| AJAX / Combination change refresh delay | 0 ms | Milliseconds to wait before reinserting videos after a combination change or AJAX product update. |
| Combination change initial delay | 0 ms | Extra delay before video re-insertion after a combination change. Leave at 0 — the slider readiness check handles timing automatically. |
| Direction of the thumbnails | Horizontal | Whether your theme displays thumbnails in a horizontal or vertical strip. |
| Video Embed z-index | 1 | CSS z-index for the embedded video element. Increase if the video appears behind other page elements such as a sticky header. |
| Fancy Box | Enabled | Opens videos in a FancyBox lightbox when a thumbnail is clicked. Disable if your theme has its own lightbox and there is a conflict. |
| Elements to Hide / Display | — | Comma-separated jQuery selectors for page elements to hide while a video is playing. They reappear when the customer switches back to a normal product image. |
| Use Deepest Selected Element | Disabled | Forces the module to target the deepest element within the selector (typically <img>). Enable if videos trigger inconsistently or do not disappear when switching back to an image. |
| Disable Thumbnails size calculation | Disabled | Prevents the module from resizing the thumbnail container after injecting video thumbnails. Enable if thumbnails push page content out of place. |
| Disable hide main image | Disabled | Stops the module from hiding the main product image when a video loads. Use for slider-based themes that display multiple images simultaneously. |
| Disable main image replacement | Disabled | Stops the module from replacing the main image element's content. Use for slider-based themes. |
| Hide Image Container | Disabled | Hides the entire main image container when a video loads, rather than only hiding the image inside it. Use for slider-based themes. |
| Additional thumbnail list width | 0 | Extra pixels added to the thumbnail container width. Use if the injected video thumbnail overflows the strip. Set to 0 to disable. |
| Disable the usage of thumbnails | Disabled | Bypasses thumbnail injection entirely. Use for themes with a large grid-style image display that does not use a thumbnail strip. |
| Disable padding in embed | Disabled | Removes the responsive padding wrapper from the video embed. Enable if the video appears oversized. |
| Delay between thumbnail changes | 0 ms | Milliseconds to wait between thumbnail change events. Use if the module fires faster than the theme's thumbnail management system, causing the previous image to reappear. |
Video Interaction Blocking (YouTube only)
These settings let you place an invisible overlay over the YouTube player to prevent direct user interaction while keeping the video visible. This is useful when displaying a background-style autoplay video and you want to hide YouTube's UI elements.
| Field | Default | Description |
|---|---|---|
| Block Video Interaction | Disabled | Adds an invisible <div> over the YouTube embed, preventing clicks, play/pause, and the YouTube controls from appearing. |
| Display play icon when paused | Enabled | Shows a circular play icon over the blocked video when it is paused. |
| Display pause icon while playing | Enabled | Shows a circular pause icon while the blocked video is playing. |
| Keep action icon displayed | Enabled | Keeps the pause/play icon permanently visible rather than letting it fade out. |
How It Works
When a customer visits a product page, the module runs JavaScript that looks up the page DOM using your configured CSS selectors. It finds the main image element, the image container, and the thumbnail list, then injects the video thumbnail into the list and positions the video embed inside the image container.
Selector matching
The module targets elements using standard jQuery selectors. If a selector returns no element — because your theme uses different class names or IDs — nothing is injected and the gallery appears unchanged. Errors appear in the browser console when Debug video generation is enabled.
Slider integration
For themes that wrap the gallery in a JavaScript slider library, the module performs extra steps after injection: it calls the slider's API to add the new thumbnail slide, and optionally refreshes the slider so the new slide is visible. The exact API call depends on the slider library selected in Custom Image Slider. If your slider library is not in the list, use the manual selector fields (PV_SLIDER_THUMB_SEL, PV_SLIDER_IMG_SEL) to define the elements the module should target.
Timing
Heavy themes sometimes initialize their sliders or AJAX-update the product gallery after the module's DOM-ready event fires. The Load delay and AJAX / Combination change refresh delay fields add a wait period before the module attempts injection, ensuring the gallery elements exist by the time the module looks for them.
Usage Examples
Example: Custom theme with a different thumbnail container class
Your theme uses .product-gallery__thumbs instead of .product-images. Open the product page in your browser, inspect the thumbnail container (F12 > click the element), copy its class. In the Theme Compatibility tab, set Selector for Thumbnails Container to .product-gallery__thumbs and save. Videos now appear in the thumbnail strip.
Example: Theme using Swiper Slider
Your marketplace theme uses Swiper for the product image gallery. Select Swiper Slider under Custom Image Slider. Set Selector for the slider's thumbnails container to the CSS selector for the element with the .swiper-container class on your product page. Enable Refresh slider after adding the items and save. The video thumbnail now appears as a slide inside the Swiper gallery.
Example: Video appears behind a sticky navigation bar
After a video loads, it is hidden underneath the site's sticky header (z-index 1000). Set Video Embed z-index to 1001 and save. The video embed now appears above the header.
Example: Videos break when switching product combinations
After changing a product attribute (size, color), the video disappears and does not reappear. Set AJAX / Combination change refresh delay to 300 and save. The module now waits 300 ms for the theme to finish updating the gallery before reinserting the video.
Important Notes
- Theme Preset auto-fills but does not auto-save. After selecting a preset, always review the filled selectors and click Save before testing.
- Slider libraries not in the list. If your theme's slider is not in the Custom Image Slider dropdown, fill in the
PV_SLIDER_THUMB_SELandPV_SLIDER_IMG_SELselector fields manually and enable Refresh slider to cover most cases. - Multi-shop. These settings are configured per-shop. If you run shops on different themes, configure the Theme Compatibility tab for each shop separately.
- Disable padding with care. Enabling Disable padding in embed removes the aspect-ratio wrapper. On some themes this creates a correctly-sized embed; on others the video collapses to zero height. Toggle it and save to see which behavior applies to your theme.
- Video Interaction Blocking is YouTube only. The invisible overlay does not work with Vimeo or HTML5 video embeds.
- Debug mode in production. Leaving Debug video generation enabled on a live store does not break anything, but it adds console output visible to any customer who opens developer tools. Disable it once your integration is working.
Troubleshooting
| Problem | Solution |
|---|---|
| Videos do not appear in the gallery | Start with the Theme Preset for your PS version. If that does not help, use browser developer tools (F12 > Inspector) to find the actual class names on the main image, image container, and thumbnail list, then update the three Core Selector fields. |
| Video appears in the wrong position | The Product main image container / Video Placeholder selector is pointing at the wrong element. Inspect the page and identify the direct wrapper around the main image. |
| Video appears behind other page elements | Increase Video Embed z-index above the z-index of the overlapping element (sticky headers are often 1000–9999). |
| Thumbnail click requires two clicks to trigger | Change Click Behaviour Type from mousedown to click. |
| Video thumbnail not visible in slider | If using Slick Slider or Owl Carousel v2, enable Refresh slider after adding the items. |
| Videos disappear after switching a product variant | Add a value of 200–500 to AJAX / Combination change refresh delay. |
| Video appears oversized or distorted | Enable Disable padding in embed and test. If still wrong, check that the Product main image container selector points to the correct container element. |
| Gallery works on page load but breaks after AJAX navigation | Enable Refresh slider after adding the items and, if needed, increase the AJAX / Combination change refresh delay. |
| Video thumbnail pushes other thumbnails off-screen | Enable Disable Thumbnails size calculation to stop the module from resizing the thumbnail container. |
Frequently Asked Questions
Q: How do I find the correct CSS selector for my theme's thumbnail container?
A: Open a product page in your browser and press F12 to open developer tools. Click the Inspector or Elements tab, then click directly on the thumbnail strip on the product page. The HTML panel highlights the element. Look at its id or class attribute — that becomes your selector, prefixed with # for IDs or . for classes.
Q: My theme uses Slick Slider and video thumbnails are injected but invisible. What should I do?
A: Enable Refresh slider after adding the items under Slider Configuration. This tells the module to call Slick's slickAdd API after injecting the thumbnail so the slider registers the new slide and makes it visible.
Q: Can I use multiple CSS selectors in a single field?
A: Yes. jQuery accepts comma-separated selectors (for example .product-cover, .product-image). However, using the most specific single selector that matches your theme avoids unintended matches on other elements.
Q: Does changing the Theme Preset overwrite my existing selectors? A: Yes. Selecting a preset auto-fills the Core Selector fields with the preset's default values. If you have customized those fields, applying a preset will replace your values. Review all three Core Selector fields after applying a preset before saving.
Q: I enabled Debug mode but I do not see any console output. What is wrong? A: Make sure you open the browser console (F12 > Console tab) before reloading the product page — the debug output is written during page initialization and will not appear if the console is opened after the page loads.
Q: Does Video Interaction Blocking work with Vimeo or HTML5 videos? A: No. The invisible overlay is YouTube only. Enabling Block Video Interaction on a product that has a Vimeo or HTML5 video will have no visible effect.
Q: Will these settings affect all shops in a multi-shop setup? A: Theme Compatibility settings are shop-specific. Switch to the shop you want to configure in the Back Office shop selector before saving changes.