Lazily embed YouTube videos with a static placeholder using the <iframe> srcdoc attribute, which looks like the YouTube embed (at the the time of writing) but doesn't actually embed until you click.

npm i astro-lazy-youtube-embed

The title and videoId params are required:

<YouTube
  title="Just Curious - Limmy's Homemade Show"
  videoId="FfTT7mxGw8I"
/>

By default, embeds use the default YouTube thumbnail for the video at sd (640px) resolution.

Use thumbnailRes to control the resolution of the YouTube thumbnail used for the placeholder - you can pass the resolution (120, 320, 480, 640, or 1280), or one of the names YouTube maps resolutions to (default, medium/mq, high/hq, standard/sd, or maxres).

Pass 1, 2, or 3 as a thumbnail param to use one of the 3 alternate thumbnails YouTube provides as the placeholder - these are screenshots from the video itself.

To use a custom thumbnail, pass a URL as the thumbnail param.

Use embedParams to pass YouTube IFrame Player API parameters for the embed, e.g. to set start & stop times to play a particular section when clicked.

Default embedParams are:

{
  // automatically start to play when the player loads
  autoplay: 1,
}

Videos are embedded using www.youtube-nocookie.com/embed by default. This is YouTube's "privacy-enhanced mode" (🧂🤏) URL, which prevents embedded videos from affecting a user's watch history if they're logged in to YouTube.

To embed using www.youtube.com/embed instead, pass a cookie flag:

<YouTube cookie ... />

The "Watch on YouTube" link from the YouTube embed is recreated, as some users prefer not to watch embedded videos, or to use the link to download the video instead.

If you want to omit this link (saving ~3.9 KB per video), pass a noLink param.

---
import {YouTube} from 'astro-lazy-youtube-embed'
---
<YouTube
  title="Just Curious - Limmy's Homemade Show"
  videoId="FfTT7mxGw8I"
/>

<div class="my-8">Configure the embed features and thumbnail size:</div>

<YouTube
  embedParams={{start: 19, end: 22}}
  thumbnailRes="maxres"
  title="Frimmerang"
  videoId="xptCWoB_VCE"
/>

<div class="my-8">Pass other HTML attributes for the <code>&lt;iframe&gt;</code>:</div>

<YouTube
  class="rounded-2xl"
  id="techno"
  title="Limmy Teaches Techno - Limmy's Homemade Show"
  videoId="L0C5nyOVTzc"
/>