Lazy Embed: A Web Component for Lazy-Loaded Video Embeds

Lazy Embed is a lightweight, customizable web component that improves website performance by lazy-loading video embeds from YouTube, Vimeo, and other sources. Videos load only when needed, saving bandwidth and improving page load speed.

Live Demo

Features

• 🚀 Performance: Only loads videos when they're needed
• 🔍 SEO-friendly: Preview images load immediately while heavy video embeds are deferred
• 🎮 Multiple trigger options: Load videos on click, visibility, or other custom events
• 📱 Responsive: Automatically adapts to different screen sizes
• 🌐 Framework-agnostic: Works in any web project - no framework required
• ✨ Simple API: Easy to implement with just a few attributes

Installation

Option 1: Direct Script Import (CDN)

Add this to your HTML page:

<script type="module" src="https://unpkg.com/@robcruiz/lazy-embed"></script>

Option 2: NPM Installation

npm install @robcruiz/lazy-embed

Then import it in your JavaScript:

// ESM import
import '@robcruiz/lazy-embed';

// Or CommonJS
require('@robcruiz/lazy-embed');

Basic Usage

<lazy-embed 
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" 
  preview-image="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  alt="YouTube video"
  video-title="Example video">
</lazy-embed>

Available Properties

Property	Description	Type	Default
src	URL of the video to embed (YouTube, Vimeo, etc.)	string	required
preview-image	URL of the preview image to display	string	required
alt	Alternative text for the preview image	string	'Video preview'
width	Width of the embed (px or %)	string	'100%'
height	Height of the embed (px or %)	string	'auto'
video-title	Title of the video (for accessibility)	string	''
load-on-visible	Load video when it becomes visible in viewport	boolean	false
load-on-parent-open	CSS selector for parent element that triggers loading when opened	string	''
load-on-click-selector	CSS selector for elements that trigger loading when clicked	string	''

Advanced Usage Examples

Load When Visible in Viewport

<lazy-embed 
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" 
  preview-image="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  load-on-visible="true">
</lazy-embed>

Load When Parent Element Opens

<div id="accordion-item">
  <button>Open Section</button>
  <div class="content">
    <lazy-embed 
      src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" 
      preview-image="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
      load-on-parent-open="#accordion-item.active">
    </lazy-embed>
  </div>
</div>

Load When External Element is Clicked

<button id="load-video-btn">Load Video</button>

<lazy-embed 
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" 
  preview-image="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  load-on-click-selector="#load-video-btn">
</lazy-embed>

Browser Support

This component works in all modern browsers that support:

• Web Components (Custom Elements v1)
• IntersectionObserver API
• MutationObserver API

Development

This component was built with Stencil.js, a toolchain for building reusable, scalable web components.

If you want to customize or contribute to this component:

# Clone the repository
git clone https://github.com/robruiz/lazy-embed.git
cd lazy-embed

# Install dependencies
npm install

# Start the development server
npm start

# Build for production
npm run build

# Run tests
npm test

Learn more about building with Stencil at their official documentation.

License

MIT