Lazy Video Docs

Overview

Embedding videos with standard <iframe> tags can dramatically slow down your site and consume large amounts of data. Each iframe loads the full video player and related resources immediately-even if the user never interacts with it. On pages with several videos, this can add hundreds of megabytes to the initial page load, resulting in a sluggish and costly experience, especially for users on mobile devices or limited networks.

How Lazy Video Helps

The <lazy-video> component solves this by loading only a lightweight thumbnail and play button at first. The actual video player is loaded only when the user clicks play (or when the video scrolls into view if autoload is enabled). This keeps your pages fast, responsive, and bandwidth-friendly.

Basic Usage

To get started, include the script on your page and use the custom element as shown below:

<lazy-video 
    src="https://www.youtube.com/embed/wPr3kws2prM"
    title="Till We Have Faces by Silent Planet">
</lazy-video>

Officially Supported Platforms

Attributes

Styling & CSS Variables

You can customize the look of <lazy-video> using CSS variables:

lazy-video {
    --lv-max-width: 600px;
    --lv-border-radius: 8px;
    --lv-play-button-color: #f00;
    --lv-play-button-bg: rgba(0, 0, 0, 0.7);
    --lv-show-title: none;
}

Examples

YouTube Embed with Custom Size

<lazy-video 
    src="https://www.youtube.com/embed/wPr3kws2prM"
    title="Till We Have Faces by Silent Planet"
    width="50%"
    height="260px"
    thumbnail-quality="maxres">
</lazy-video>

Bitchute with Autoload Off

<lazy-video 
    src="https://www.bitchute.com/video/zSfeNPF-OpY"
    title="Trump Assassination Attempt Documents LOCKED Away. What are they Hiding?"
    autoload="false"
    thumbnail="https://static-3.bitchute.com/live/cover_images/nDPZqzyLkFKW/zSfeNPF-OpY_640x360.jpg">
</lazy-video>

Bitchute with Autoload

<lazy-video 
    src="https://www.bitchute.com/video/zSfeNPF-OpY"
    title="Trump Assassination Attempt Documents LOCKED Away. What are they Hiding?">
</lazy-video>

Responsive Container (FitVids Style)

<div style="max-width: 100%; width: 100%;">
    <lazy-video 
        src="https://www.youtube.com/embed/wPr3kws2prM"
        title="Responsive container example"
        container-fit="true">
    </lazy-video>
</div>

YouTube with Hidden Title Bar

<lazy-video 
    src="https://www.youtube.com/embed/wPr3kws2prM"
    title="Hidden title example"
    hide-title>
</lazy-video>

Global Title Control with CSS

/* Hide titles for all videos */
lazy-video {
    --lv-show-title: none;
}

/* Hide titles for a group */
.article-videos lazy-video {
    --lv-show-title: none;
}

Global Alignment Control with CSS

/* Set alignment for all videos */
lazy-video {
    --lv-align: left;
}

/* Responsive alignment */
@media (max-width: 768px) {
    lazy-video {
        --lv-align: center;
    }
}

/* Different alignments for different contexts */
.sidebar lazy-video {
    --lv-align: right;
}

Converting Existing iframes

You can convert existing video iframes to <lazy-video> by simply changing the tag name.

Standard YouTube iframe:

<iframe 
    src="https://www.youtube.com/embed/wPr3kws2prM?start=30&rel=0&controls=0" 
    width="560" 
    height="315" 
    title="Till We Have Faces by Silent Planet" 
    frameborder="0" 
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
    allowfullscreen>
</iframe>

Converted to <lazy-video> (just change the tag):

<lazy-video 
    src="https://www.youtube.com/embed/wPr3kws2prM?start=30&rel=0&controls=0" 
    width="560" 
    height="315" 
    title="Till We Have Faces by Silent Planet" 
    frameborder="0" 
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
    allowfullscreen>
</lazy-video>

Security & Privacy

<lazy-video> is built with modern web security and privacy best practices:

• All embedded iframes use the credentialless attribute. This helps prevent credential leaks and keeps third-party content isolated from your site's cookies and storage.
• The sandbox attribute is set by default, restricting what the embedded player can do and reducing risk from third-party content.
• For YouTube, the youtube-nocookie.com domain is used by default, so no tracking cookies are set unless the user interacts with the video.

Browser Support

Works in all modern browsers (Chrome, Firefox, Safari, Edge). Uses standard web component APIs. For IE11 or older, use the custom-elements polyfill.

Breaking Change

April 3, 2025: The old <lazy-youtube> element is no longer supported. Please update any code to use <lazy-video> instead.