Saltar al contenido principal

Slider Integration

Connects Product Video to your theme's JavaScript image slider so video thumbnails appear correctly inside the slider and the slider stays functional after they are added.

nota

Available since v3.0.0

Overview​

Many themes replace the default product image list with a JavaScript slider library — Slick, Swiper, Owl Carousel, and others. Each of these libraries manages its own internal DOM structure and slide count. When Product Video injects a video thumbnail into the page, a slider that doesn't know about the new slide may hide it, break its navigation, or throw a JavaScript error.

Slider Integration solves this by telling the module which slider library your theme uses. Once selected, the module loads a compatibility layer that injects video thumbnails in the format that slider expects. You can also provide jQuery selectors for the specific container elements, add wrapper HTML around each injected slide, sync two sliders that move together, and force the slider to refresh its internal state after the new slides are added.

You only need to configure this section if your theme's product image gallery uses one of the supported slider libraries. If your theme uses a plain image list without a slider, leave Custom Image Slider set to none and skip this section.

Configuration​

  1. Go to Modules > Module Manager, find Product Video, and click Configure.
  2. Open the Theme Compatibility tab.
  3. Scroll down to the Slider Configuration section.
FieldValuesDefaultDescription
Custom Image SliderNone, Slick Slider, BX Slider, Owl Carousel Old (prior to 2.0), Owl Carrousel, Swiper Slider, Flickity Carousel, Light Slider, Bootstrap 5 CarouselNoneThe slider library your theme uses. Selecting a library loads the correct compatibility layer for that slider.
Selector for the slider's thumbnails containerjQuery selector string—Points to the container element the slider uses for thumbnails. Leave blank if your slider is auto-detected. See library defaults below.
Selector for the Main Image's sliderjQuery selector string—Points to the main (large) image slider element if your theme uses a separate slider there. Only fill this in if there is a distinct main-image slider.
Main Image's Slider HTML (before)Raw HTML string—HTML that the module injects immediately before each image slide. Use this when your slider requires a wrapper element around each slide item.
Main Image's Slider HTML (after)Raw HTML string—HTML that the module injects immediately after each image slide. Pair with the before field to open and close wrapper tags.
Sync thumbnail and image slidersYes / NoNoWhen enabled, selecting a thumbnail also moves the main image slider to the matching position. Enable only if your theme uses a synced thumb + main-image slider pair.
Refresh slider after adding the itemsYes / NoNoForces the slider library to re-initialize after video thumbnails are injected. Required for Slick Slider and Owl Carousel v2 when new slides don't appear.

When Sync thumbnail and image sliders is enabled, the module automatically disables the autosize feature, because synced sliders manage their own sizing. A confirmation message in the Back Office will remind you of this if it applies.

How It Works​

When you select a slider library, the module switches to slider-aware injection mode. Instead of appending thumbnail elements to a plain list, it targets the selector you provide and inserts slides in a format the slider can render.

The before and after HTML fields let you wrap each injected slide in whatever markup your slider variant requires — for example, Bootstrap 5 Carousel needs <div class="carousel-item"> around each slide.

If Refresh slider is enabled, the module triggers the appropriate re-initialization event after injection. For Slick, this means calling slickAdd or re-triggering initialization. For Owl Carousel v2, it dispatches refresh.owl.carousel. This step is what makes the slider re-count its slides and show navigation dots or arrows for the newly added video.

If Sync is enabled, the module also moves the main image slider in step whenever a video thumbnail is selected from the thumbnail strip.

Library-Specific Defaults​

Slick Slider​

  • Thumbnails container selector: A selector pointing to the element with the slick-slider class, for example .slick-slider or .product-images .slick-slider.
  • Refresh slider: Enable this. Slick does not automatically detect new slides — it needs a re-initialization call after injection.
  • Sync: Enable if your theme runs a synced main/thumb Slick setup, and fill in both selectors.

BX Slider​

  • Thumbnails container selector: The selector for the <ul> element that BX Slider is initialized on.
  • Refresh slider: Typically not needed — BX Slider handles dynamic content better than Slick.
  • Thumbnails container selector: Use #thumbs_list_frame or the specific Owl container selector your theme defines.
  • Refresh slider: Not needed for Owl v1.

Owl Carrousel (v2)​

  • Thumbnails container selector: The selector for the Owl v2 container div.
  • Refresh slider: Enable this. Owl v2 requires a trigger('refresh.owl.carousel') event after adding new items.

Swiper Slider​

  • Thumbnails container selector: The selector for the DOM element with the .swiper-container class (or .swiper in Swiper 8+).
  • Main Image selector: Fill this in if there is a separate main-image Swiper instance.
  • Sync: Enable if your theme uses Swiper's built-in thumb gallery sync.
  • Thumbnails container selector: The selector for the Flickity-initialized element.
  • Refresh slider: Usually not needed — Flickity handles appended items without a full re-initialization.

Light Slider​

  • Thumbnails container selector: The selector for the Light Slider container element.
  • Thumbnails container selector: The selector for the .carousel container.
  • Main Image's Slider HTML (before): Enter <div class="carousel-item"> — Bootstrap 5 requires this wrapper around each slide.
  • Main Image's Slider HTML (after): Enter </div> to close the wrapper.

Usage Examples​

Example: Slick Slider theme with a thumbnail strip

Your theme uses Slick for both the main image and the thumbnail strip below it, synchronized.

  1. Set Custom Image Slider to Slick Slider.
  2. In Selector for the slider's thumbnails container, enter .product-images .slick-slider (adjust to match your theme's markup).
  3. In Selector for the Main Image's slider, enter .product-cover .slick-slider.
  4. Enable Sync thumbnail and image sliders.
  5. Enable Refresh slider after adding the items.
  6. Save. Video thumbnails now appear as Slick slides in both the thumbnail strip and the main image area, in sync.

Example: Swiper Slider with no sync

Your theme uses a single Swiper for thumbnails, no separate main-image slider.

  1. Set Custom Image Slider to Swiper Slider.
  2. In Selector for the slider's thumbnails container, enter .swiper-container or the more specific selector your theme uses.
  3. Leave Selector for the Main Image's slider blank.
  4. Leave Sync disabled.
  5. Save. The module appends video thumbnails as Swiper slides and the carousel works as usual.

Example: Bootstrap 5 Carousel

Your theme wraps each product image in a Bootstrap 5 carousel item.

  1. Set Custom Image Slider to Bootstrap 5 Carousel.
  2. In Main Image's Slider HTML (before), enter <div class="carousel-item">.
  3. In Main Image's Slider HTML (after), enter </div>.
  4. Set Selector for the slider's thumbnails container to .carousel.
  5. Save. Each injected video thumbnail is wrapped in a proper carousel item and the Bootstrap carousel renders it correctly.

Important Notes​

  • The Custom Image Slider dropdown lists the supported libraries only. If your theme uses a custom or proprietary slider not in the list, choose the closest match and adjust the selector and HTML wrapper fields manually.
  • Owl Carousel has two separate entries: Owl Carousel Old (v1, prior to 2.0) and Owl Carrousel (v2). Select the version that matches your theme. Using the wrong version will cause the refresh trigger to do nothing.
  • This section is only relevant when the image gallery placement is in use. If you are displaying videos in the side panel, content tab, or product listings only, slider integration has no effect.
  • When Sync thumbnail and image sliders is enabled, Autosize is automatically disabled for the video player. This is intentional — synced sliders control sizing themselves and autosize interferes.
  • The Refresh slider toggle adds a re-initialization step that can cause a brief visual flicker when the product page loads and the slider re-renders. This is normal.
  • Selector fields accept any valid jQuery selector. Test selectors in your browser's developer console with $('your-selector') to confirm they match the right element before saving.

Troubleshooting​

ProblemSolution
Video thumbnail is injected but not visible in the sliderEnable Refresh slider after adding the items. The slider's internal slide count is out of date and hiding the new slide.
The slider breaks completely after the video thumbnail is addedThe slide markup the module injected doesn't match what the slider expects. Check what HTML wraps each image slide in your theme, then add the opening tag to Main Image's Slider HTML (before) and the closing tag to Main Image's Slider HTML (after).
Thumbnail strip slides but the main image doesn't followEnable Sync thumbnail and image sliders and make sure both the thumbnail selector and the main image selector are filled in and pointing to the correct elements.
No slider option in the list matches my themeSelect the library that is closest to what your theme uses, then manually adjust selectors and wrapper HTML. If still broken, set Custom Image Slider to none and rely on the plain CSS selectors in the Theme Compatibility section.
Video thumbnail appears outside the slider entirelyThe Selector for the slider's thumbnails container is incorrect or empty. Open your browser's developer tools, inspect the slider container, copy a unique selector for it, and paste it into that field.
Slider flickers or re-animates on every page loadThis is caused by the Refresh slider step. It is expected behavior. If the flicker is unacceptable, contact your theme developer about a native hook that fires when the slider finishes initializing, then disable the refresh toggle.

Frequently Asked Questions​

How do I know which slider library my theme uses?

Open your store's product page, right-click the image gallery, and choose "Inspect element". Look at the CSS classes on the slider container — class names like `slick-initialized`, `swiper-container`, `owl-carousel`, or `flickity-enabled` identify the library. You can also check your theme's JavaScript files for the library name.

Do I need to configure this if videos show up correctly already?

No. If video thumbnails appear correctly in your slider without any configuration here, leave everything at the default (no slider selected). The slider settings are only needed when thumbnails are missing, hidden, or causing the slider to break.

What is the difference between "Owl Carousel Old" and "Owl Carrousel" in the dropdown?

"Owl Carousel Old" targets Owl Carousel version 1 (prior to 2.0). "Owl Carrousel" targets Owl Carousel version 2 and later. Version 2 uses a different API for re-initialization and requires the **Refresh slider** toggle to be enabled. If you select the wrong version, the refresh trigger won't work and new slides may not appear.

Can I use slider integration together with the side panel or content tab display modes?

Yes, but slider integration only affects the image gallery placement. If you are also showing videos in the side panel or content tab, those placements are independent of the slider and don't require slider configuration.

My theme uses Swiper 8 — which class should I use as the container selector?

Swiper 8 changed the main container class from `.swiper-container` to `.swiper`. Use `.swiper` as your thumbnails container selector when your theme uses Swiper 8 or later.

Does enabling Sync affect how the video plays?

Sync only controls slider position — it keeps the thumbnail strip and main image slider in step when a thumbnail is clicked. It does not affect video playback or the video player itself.