Fast, Lightweight YouTube Video Embed Web Component – lite-youtube

lite-youtube is a tiny web component that provides a performance-optimized way to embed YouTube videos on your website. It significantly improves page load times by deferring the heavy YouTube iframe until user interaction.

The web component serves as the ShadowDom web component version of Paul’s lite-youtube-embed component. It uses a lightweight placeholder image initially, then loads the full YouTube player only when needed. This approach delivers substantial performance improvements.

Features:

• Zero dependencies and pure vanilla JavaScript implementation
• Shadow DOM encapsulation for clean integration
• Responsive 16:9 aspect ratio that maintains layout stability
• Keyboard accessibility with ARIA support
• Localization support for play button labels
• Lazy loading capabilities using Intersection Observer
• Support for both standard videos and YouTube Shorts
• WebP image optimization with JPEG fallback
• Flexible customization through CSS properties
• and more

How to use it:

1. Install and import the lite-youtube web component.

# Yarn
$ yarn add @justinribeiro/lite-youtube
# NPM
$ npm install @justinribeiro/lite-youtube

import '@justinribeiro/lite-youtube';

2. You can also directly import it into your HTML document from a CDN.

<script type="module" src="https://cdn.jsdelivr.net/npm/@justinribeiro/lite-youtube@1/lite-youtube.min.js"></script>

3. Add the <lite-youtube> custom element to your page and set the video ID & playlist (OPTIONAL) as follows:

<lite-youtube videoid="VIDEO ID HERE"></lite-youtube>

<lite-youtube videoid="VIDEO ID HERE" playlistid="PLAYLIST ID"></lite-youtube>

4. Add a fallback link for enhanced accessibility:

<lite-youtube videoid="guJLfqTFfIw">
<a class="lite-youtube-fallback" href="https://www.youtube.com/watch?v=guJLfqTFfIw">Watch on YouTube</a>
</lite-youtube>

5. Enable mobile-optimized layout for Youtube Shorts:

<lite-youtube videoid="VIDEO ID" short></lite-youtube>

6. Delay the loading of YouTube video until it’s scrolled into view using the Intersection Observer API:

<lite-youtube videoid="VIDEO ID" autoload> </lite-youtube>

7. More props to customize the component.

• videoid: The YouTube video ID. (Required)
• playlistid: The YouTube playlist ID. Requires a videoid for the thumbnail.
• videotitle: The title of the video. Defaults to “Video”.
• videoplay: The title of the play button (used for translation). Defaults to “Play”.
• videoStartAt: Sets the point at which the video should start, in seconds. Defaults to 0.
• posterquality: Sets the thumbnail poster quality. Options are: maxresdefault, sddefault, mqdefault, hqdefault. Defaults to hqdefault.
• posterloading: Sets the img lazy loading attribute for the poster image. Defaults to lazy.
• nocookie: Uses youtube-nocookie.com as the iframe embed URI. Defaults to false.
• autoload: Uses Intersection Observer to load the iframe when scrolled into view. Defaults to false.
• short: Shows a 9:16 YouTube Shorts-style interaction on mobile devices. Defaults to false.
• params: Sets YouTube query parameters.
• disablenoscripts: Inject into the lightdom a noscript for SEO help.
• autopause: Auto-Pause video when scrolled out of view.

8. Customize the appearance of your Youtube embed.

lite-youtube::part(playButton) {
  /* You styles here */
}
lite-youtube {
  /* Video aspect ratio */
  --lite-youtube-aspect-ratio: 2 / 3;
}
lite-youtube {
  /* disable the frame shadow */
  --lite-youtube-frame-shadow-visible: no;
}

Changelog:

v1.9.0 (05/20/2025)

• Load playlist thumbnails using YouTube oEmbed
• fix(iframe): adds strict-origin-when-cross-origin referrerpolicy to iframe to help resolve player error

v1.8.2 (05/20/2025)

• fix(autopause): stop overriding custom params

v1.8.1 (04/30/2025)

• fix(firefox): position absolute with slot does not assume 0

v1.8.0 (04/26/2025)

• feat(noscript): allow disabling of noscript lightdom inject
• doc(autopause): clarify custom poster behavior
• feat: add support for stying the playButton