PolyCMS
Back to Main Site

YouTube Video Gallery and Slider Integration Guide

Last updated on May 29, 2026 15:23

Introduction

Video content is one of the most effective tools for showcasing products, providing technical tutorials, and building user trust. PolyCMS features a highly optimized and performant YouTube Gallery block that allows you to embed multi-video layouts on any page.

Rather than loading heavy, slow individual video embeds that drag down page scores, the YouTube Gallery is custom-designed for rapid loads, responsive flexibility, and sophisticated playback monitoring.

Multiple Layout Configurations

The YouTube Gallery block supports 4 custom-tailored layouts to suit various design aesthetics and content density needs:

1. Continuous Autoplay Slider Layout (slider)

An elegant, high-engagement carousel layout that scrolls horizontally. It supports:

  • Columns (sliderVisibleItems): Set how many videos are visible at once in the carousel frame.
  • Autoplay Control: Automatically scrolls the carousel at standard intervals.
  • Continuous Loop Mode: Seamlessly loops video slides infinitely in a smooth pixel-by-pixel scroll using a requestAnimationFrame render loop.
  • Scroll Direction: Supports both Left-to-Right (left) and Right-to-Left (right) scroll paths.

2. Interactive Hero Gallery Layout (gallery)

Designed for tutorials, product demos, and showcases:

  • Hero Frame: A large, prominent main video player is positioned at the top.
  • Thumbnails Row: A horizontal grid of video thumbnails lies below the player.
  • Instant Swapping: Clicking any thumbnail triggers an optimized inline JavaScript event that immediately updates the Hero player's source URL without refreshing the page.

3. Responsive Grid Layout (grid)

The default layout. It automatically distributes your video embeds inside a clean, modern grid. It is built using lightweight CSS grid rules that automatically adapt to the user's viewport:

  • Mobile devices: Stacks videos in a single column to maintain readability.
  • Tablets and Desktops: Organizes videos in a harmonized 2-column or 3-column layout with a standard 16px gutter.

4. Streamlined List Layout (list)

A classic, stacked flow. It aligns videos vertically, maintaining a rigid 16:9 aspect ratio. This is ideal for step-by-step video courses or sequential course guides.

Advanced YouTube Iframe API Integration

The YouTube Gallery slider features a premium, intelligent playback monitoring engine that guarantees a flawless user experience.

The Challenge with Standard Carousels

In most web carousels, if a user clicks play on a video inside an autoplaying slider, the slider will continue to scroll, moving the active video out of the viewport while the audio keeps playing in the background.

The PolyCMS Solution

PolyCMS solves this by dynamically loading and integrating the YouTube Iframe API:

graph TD A[Slider Autoplay Active] --> B[Load YouTube Iframe API] B --> C[Initialize YT.Player on Iframe] C --> D[Monitor state changes via onStateChange] D --> E{Video state = PLAYING or BUFFERING?} E -->|Yes| F[Pause Slider Autoplay] E -->|No| G{Are other videos playing?} G -->|Yes| F G -->|No| H[Resume Slider Autoplay]
  1. API Loading: The renderer automatically detects if autoplay or continuous slider mode is active and injects the YouTube Iframe API script exactly once.
  2. Player Initialization: It hooks into onYouTubeIframeAPIReady and registers a YT.Player instance on every video frame inside the slider.
  3. Smart Play State Detection: It monitors state changes (onStateChange). When a video is started (1 = PLAYING) or begins buffering (3 = BUFFERING), the script instantly sets a global playing flag to true, pausing the slider immediately so the user can watch the video uninterrupted.
  4. Auto-Resume: Once the video is paused, ended, or encounters an error, the script resets the flag and smoothly resumes the slider's carousel movement.

Live Interactive Demos

To showcase the robust styling and interactivity capabilities of the PolyCMS YouTube Gallery block, below are live, functional demonstrations of all supported layout modes, prioritized by our premium slider and gallery layouts.

1. Advanced Autoplay Sliders

A premium horizontal carousel slider. It supports custom parameters for column numbers, slide auto-triggering, continuous rolling, and direction.

  • Play State Lock (A11y): Built-in YouTube Iframe API event listener pauses the scrolling action immediately when a video starts playing so readers can watch undisturbed, resuming slide movement once the video is paused.

Example A: 3-Column Continuous Left-to-Right Scroll

Renders 3 visible videos simultaneously with a smooth, continuous pixel-by-pixel scrolling loop in the Left-to-Right direction (content moves left):

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="slider" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]' data-slider-visible-items="3" data-slider-autoplay="true" data-slider-continuous="true" data-slider-direction="left"></div>

Example B: 3-Column Continuous Right-to-Left Scroll

Renders 3 visible videos simultaneously with a continuous pixel-by-pixel scrolling loop in the Right-to-Left direction (content moves right):

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="slider" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]' data-slider-visible-items="3" data-slider-autoplay="true" data-slider-continuous="true" data-slider-direction="right"></div>

Example C: 2-Column Standard Autoplay (Left-to-Right Snap)

Renders 2 visible videos simultaneously. Slides sequentially to the left after 5 seconds instead of rolling continuously, snapping cleanly to the center of each video card:

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="slider" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]' data-slider-visible-items="2" data-slider-autoplay="true" data-slider-continuous="false" data-slider-direction="left"></div>

Example D: 2-Column Standard Autoplay (Right-to-Left Snap)

Renders 2 visible videos simultaneously. Slides sequentially to the right after 5 seconds instead of rolling continuously, snapping cleanly to the center of each video card:

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="slider" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]' data-slider-visible-items="2" data-slider-autoplay="true" data-slider-continuous="false" data-slider-direction="right"></div>

2. Interactive Hero Gallery Layout

Best suited for product showcases, landing page headers, or dashboard tours. It sets up a master active Hero video frame at the top and arranges detailed video thumbnails below it. Clicking any thumbnail triggers a fast script to swap the hero iframe source immediately without loading a new page.

Here is the live Gallery layout:

Video Thumbnail
Video Thumbnail
Video Thumbnail
Video Thumbnail
Video Thumbnail
Video Thumbnail

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="gallery" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]'></div>

3. Responsive Grid Layout

Ideal for listing multiple videos in a compact, structured matrix. Built on top of CSS Grid, it dynamically adapts to the user's screen size: rendering in a single column on mobile screens, and distributing automatically into a 2-column or 3-column matrix on desktops.

Here is the live Grid gallery in action:

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="grid" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]'></div>

4. Streamlined List Layout

Highly effective for sequential contents, video courses, or step-by-step video tutorials. Videos stack vertically in a unified stream, retaining comfortable padding between cards.

Here is the live List layout:

How to implement via HTML/Markdown:

<div data-youtube-gallery="" layout="list" data-urls='["https://www.youtube.com/watch?v=hSYz-rvOtl8","https://www.youtube.com/watch?v=UE3_Lgj4FqA","https://www.youtube.com/watch?v=C_QAOi0_qpg","https://www.youtube.com/watch?v=9P4Tq1xR3t8","https://www.youtube.com/watch?v=ez5WoORf7KM","https://www.youtube.com/watch?v=HWWotdfNWyk"]'></div>

PolyCMS is an open-source content management system for modern web applications, inspired by the WordPress plugin and theme ecosystem but built on top of the Laravel framework. It is designed to provide a complete foundation for content publishing, e-commerce, multi-language support, and extensible module architecture — powered by a Vue 3 admin panel with data served entirely through RESTful APIs.

Whether you're building a blog, a documentation site, an online store, or a multi-tenant SaaS platform, PolyCMS aims to give you a comprehensive starting scaffold so you can ship quickly and extend easily through integrated modules and themes. In particular, themes in PolyCMS follow a multi-theme architecture — one Main theme and an unlimited number of Sub themes can run side by side on the same installation.

We hope this ready-made foundation proves useful for building your next website, blog, or web app, saving you from having to start completely from scratch.

Get Started →