rt-video

rt-video is a lightweight JavaScript utility that creates highly customizable, lazy-loaded, and scroll-autoplaying video players using Plyr with:

• Automatic dependency loading (no manual installs for Plyr JS/CSS)
• Zero-config defaults (works out of the box)
• Attribute-driven configuration (supports both data-rt-video-* and rt-video-*)
• Support for multiple instances and responsive video URLs
• A clean global API under window.RtVideo
• Defensive fallbacks to avoid runtime crashes
• Seamless custom UI states (loading, active, thumbnails, and play buttons)

Primary dependency (GitHub): https://github.com/sampotts/plyr

Table of Contents

• 1. Installation
  • 1.1 CDN (jsDelivr)
  • 1.2 npm
• 2. Quick Start
• 3. Activation Rules
• 4. Configuration (HTML Attributes)
• 5. Multiple Instances
• 6. Global API
• 7. Troubleshooting
• 8. License

1. Installation

1.1 CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-video@latest/dist/index.min.js"></script>

1.2 npm

npm install @rethink-js/rt-video

Then bundle or load dist/index.min.js as appropriate for your build setup.

2. Quick Start

Add the script to your page. Construct your video wrapper with the required url, thumbnail, and button attributes. rt-video will automatically load Plyr, hide the native UI behind your custom thumbnail, and handle the playback logic.

Example:

<div rt-video rt-video-url="https://example.com/video.mp4">
  <img src="thumbnail.png" rt-video-thumbnail alt="Thumbnail" />
  <div rt-video-button>Play Video</div>
</div>

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-video@latest/dist/index.min.js"></script>

Note: You can use either data-rt-video-* or rt-video-* for all attributes. They function identically.

3. Activation Rules

The library activates when any of the following are true:

• A wrapper element containing the rt-video (or data-rt-video) attribute is detected.
• Inside the wrapper, elements with rt-video-thumbnail and rt-video-button are present.

If the required wrapper and internal UI elements are found, the library will initialize the instance, inject necessary CSS, and fetch the Plyr dependency.

4. Configuration (HTML Attributes)

Core Setup Attributes

| Attribute | Description | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | | rt-video | (Required) Marks the wrapper element to be initialized. | | rt-video-url | (Required) Source URL (YouTube or MP4). Supports responsive breakpoints (e.g., desktop.mp4, 991:tablet.mp4, 479:mobile.mp4). | | rt-video-thumbnail | (Required) Added to the image/div that acts as the custom video cover. | | rt-video-button | (Required) Added to the element that acts as the custom play button. |

Playback & Feature Attributes

| Attribute | Description | Default | | :------------------- | :---------------------------------------------------------------------------------------- | :------ | | rt-video-autoplay | Enables scroll-based autoplay (auto-pauses when out of view). Forces muted=true. | false | | rt-video-lazy | Defers initialization and Plyr loading until the wrapper is within 200px of the viewport. | false | | rt-video-muted | Mutes the video on load. | false | | rt-video-loop | Loops the video indefinitely. | false | | rt-video-start | Start time in seconds. Safely injects media fragments (#t=) or YouTube API params. | null | | rt-video-end | End time in seconds. Loops or stops when this time is reached. | null | | rt-video-volume | Initial volume level (e.g., 0.5 or 50). | null | | rt-video-autopause | Pauses this video automatically if another Plyr instance starts playing. | false |

UI Customization

| Attribute | Description | Default | | :------------------ | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- | | rt-video-controls | Comma-separated list of Plyr controls (e.g., play, progress, mute, fullscreen). Pass an empty string for no controls. | play, progress, current-time, mute, volume, fullscreen | | rt-video-color | Brand color for the Plyr UI. Accepts HEX codes or CSS variables (e.g., #ff0000 or --brand-color). | #131313 |

5. Multiple Instances

rt-video natively supports multiple independent instances on the same page.

Each instance:

• Has its own configuration and breakpoints.
• Will lazy-load independently if rt-video-lazy="true" is applied.
• Can interact with other instances (e.g., pausing others if rt-video-autopause is active).

6. Global API

The package automatically initializes on DOMContentLoaded. However, if you are dynamically injecting video elements into the DOM after the initial page load (e.g., via AJAX or a modern framework router), you can manually re-trigger the initialization.

window.RtVideo;

Methods

| Method | Description | | :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | | RtVideo.init() | Scans the DOM for uninitialized [rt-video] wrappers, loads dependencies if needed, and safely initializes new instances without duplicating existing ones. |

7. Troubleshooting

Player is not initializing

• Ensure the wrapper has the rt-video attribute.
• Ensure both the rt-video-thumbnail and rt-video-button elements exist inside the wrapper. The script skips initialization without them.

Autoplay is not working

• Autoplay videos must be muted to comply with modern browser policies. The script attempts to enforce this automatically, but ensure no conflicting scripts are overriding the volume.
• If using rt-video-autoplay, the video plays when 10% of the element is in view. Check for overlapping elements blocking the IntersectionObserver.

Responsive URLs are loading the wrong video

• Ensure your rt-video-url string is formatted strictly as default_url, max-width:override_url.
• Example: high-res.mp4, 991:medium-res.mp4, 479:low-res.mp4.

8. License

MIT License

Package: @rethink-js/rt-video GitHub: https://github.com/Rethink-JS/rt-video

by Rethink JS https://github.com/Rethink-JS