@synqro/player

Replace a custom thumbnail with a YouTube, Vimeo, or HTML5 video player on click. Ultra-lightweight facade pattern for Webflow.

Installation

Add this script in Project Settings → Custom Code → Footer Code:

<!-- [Synqro Labs] Player -->
<script src="https://cdn.jsdelivr.net/npm/@synqro/player@1/dist/index.min.js"></script>

Setup in Webflow

1. Create a Div Block with your desired dimensions (e.g. 16:9 aspect ratio)
2. Place your thumbnail image and play button inside (design them however you like)
3. Add the sl-player attribute with the video URL on the Div Block

<!-- YouTube -->
<div sl-player="https://www.youtube.com/watch?v=dQw4w9WgXcQ">
  <img src="my-thumbnail.jpg" alt="Video preview" />
  <div class="play-button">▶</div>
</div>

<!-- Vimeo -->
<div sl-player="https://vimeo.com/123456789">
  <img src="vimeo-thumbnail.jpg" alt="Video preview" />
  <div class="play-icon"></div>
</div>

<!-- Direct video (.mp4, .webm) -->
<div sl-player="https://example.com/video.mp4">
  <img src="thumbnail.jpg" alt="Video preview" />
  <div class="btn-play"></div>
</div>

On click, the thumbnail fades out and the video player takes its place with autoplay.

CMS Usage

Perfect for CMS pages: bind attributes to your Collection fields.

<div sl-player="{CMS field: Video URL}">
  <img src="{CMS field: Thumbnail}" alt="Preview" />
  <div class="play-button">Play</div>
</div>

• Video URL: plain text field containing a YouTube, Vimeo, or .mp4 link
• Thumbnail: image field with the custom preview image

Options

| Attribute | Example | Description | | ------------------- | ----------------------------------- | --------------------------------------------------------------------- | | sl-player | "https://youtube.com/watch?v=..." | Video URL (required). Auto-detects YouTube, Vimeo, or direct video | | sl-player-muted | "true" | Start muted (default: false) | | sl-player-loop | "true" | Loop the video (default: false) | | sl-player-start | "30" | Start time in seconds (default: 0) | | sl-player-params | "cc_load_policy=1" | Extra iframe parameters (advanced) | | sl-player-restore | "true" | Show thumbnail again when video is paused or ended (default: false) |

Examples:

<!-- Looping video, starting at 10s -->
<div
  sl-player="https://youtube.com/watch?v=dQw4w9WgXcQ"
  sl-player-loop="true"
  sl-player-start="10"
>
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>

<!-- Muted autoplay (recommended for mobile) -->
<div sl-player="https://example.com/video.mp4" sl-player-muted="true">
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>

Supported URLs

The script auto-detects the video type:

| Provider | Supported formats | | -------- | -------------------------------------------------------------------------------------------- | | YouTube | youtube.com/watch?v=..., youtu.be/..., youtube.com/embed/..., youtube.com/shorts/... | | Vimeo | vimeo.com/123456, vimeo.com/123456/hash (private videos) | | HTML5 | Any direct link to a video file (.mp4, .webm, etc.) |

Restore Mode

With sl-player-restore="true", the thumbnail reappears when the user pauses the video or when it ends. A new click resumes playback.

<div
  sl-player="https://youtube.com/watch?v=dQw4w9WgXcQ"
  sl-player-restore="true"
>
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>

How it works:

1. Click → thumbnail fades out, video starts playing
2. Pause (or video ends) → thumbnail fades back in
3. Click again → video resumes where it left off

YouTube and Vimeo APIs are loaded automatically (only when needed).

CSS

The script adds the sl-player-active class to the wrapper while the video is playing. Useful for styling:

/* Hide play button when video is active */
.sl-player-active .play-button {
  display: none;
}

Plyr Integration (optional)

For custom-styled controls on direct videos (.mp4), load Plyr separately:

<link rel="stylesheet" href="https://cdn.plyr.io/3.8.4/plyr.css" />
<script src="https://cdn.plyr.io/3.8.4/plyr.js"></script>

The script auto-detects Plyr and uses it for HTML5 videos. No extra configuration needed.

Tips

• Aspect ratio: Use Webflow's native aspect ratio on the Div Block (16:9 recommended)
• Mobile: Add sl-player-muted="true" for reliable autoplay on mobile
• Empty CMS fields: If the URL field is empty, the script silently ignores the element
• Multiple videos: Each [sl-player] wrapper is independent, no limit on count