Static Site Generators in Production

Lazy-Loading YouTube Embeds on Static Sites

A standard YouTube embed costs roughly 780 KB of transfer and 310 ms of main-thread time on a mid-tier phone — before the reader decides whether they want to watch anything. On a documentation page where the video is a supplement rather than the point, most readers never press play, so that cost buys nothing.

The fix is a facade: render a poster image and a play button at build time, and swap in the real iframe on click. This guide builds one that is accessible, layout-stable and generator-agnostic, then measures what it saves. It is the detailed version of the facade pattern recommended in Third-Party Script Performance on Static Sites.

Prerequisites

  • A static generator with a shortcode, component or template partial you can call from content (Hugo shortcodes, Astro components, Eleventy shortcodes, MDX components).
  • A build step that can download and optimise a poster image, or the willingness to commit posters to the repository.
  • A CSS aspect-ratio wrapper, so the facade and the player occupy the same box — see Reserving Space for Images and Embeds.

What the Facade Replaces

Facade versus embedded player on first load Two panels. The embedded player loads 780 kilobytes across four third-party origins and uses 310 milliseconds of main thread on every page view. The facade loads a 24 kilobyte poster from the site's own origin and uses 2 milliseconds, deferring the player until a click. Everyone pays, or only the people who watch Embedded player 780 KB · 4 origins 310 ms main thread paid on 100% of page views player cookies set immediately iframe grows after load Poster facade 24 KB · own origin 2 ms main thread player loads on click only no third-party cookies until then same box before and after Measured with the Lighthouse third-party summary on a mid-tier Android profile, fast 3G
The facade is not a lighter player — it is no player at all until someone asks for one, which is why the saving is proportional to how few readers press play.

The Recipe

1. Fetch the poster at build time

Hot-linking the platform's thumbnail keeps a third-party connection, so download it during the build and optimise it like any other image:

// scripts/fetch-posters.mjs — run before the build
import { mkdir, writeFile } from 'node:fs/promises';
import sharp from 'sharp';

const ids = process.argv.slice(2);
await mkdir('public/img/posters', { recursive: true });

for (const id of ids) {
  const res = await fetch(`https://i.ytimg.com/vi/${id}/maxresdefault.jpg`);
  if (!res.ok) throw new Error(`poster fetch failed for ${id}: ${res.status}`);
  const buf = Buffer.from(await res.arrayBuffer());
  await sharp(buf).resize(1280, 720, { fit: 'cover' }).avif({ quality: 60 })
    .toFile(`public/img/posters/${id}.avif`);
  await writeFile(`public/img/posters/${id}.jpg`, await sharp(buf).jpeg({ quality: 72 }).toBuffer());
}
console.log(`fetched ${ids.length} poster(s)`);

Commit the output or cache it between builds. Either way the reader gets a 20-30 KB AVIF from your own domain rather than a 90 KB JPEG from a fourth origin.

2. Render the facade as a real button

Accessibility is where this pattern is usually botched. A div with a click handler cannot be reached by keyboard and announces nothing useful. Use a button:

<figure class="video">
  <button class="video-facade" data-video-id="dQw4w9WgXcQ"
          aria-label="Play video: Deploying a static site to the edge (7 min)">
    <img src="/img/posters/dQw4w9WgXcQ.avif" width="1280" height="720" alt=""
         loading="lazy" decoding="async">
    <span class="video-facade-play" aria-hidden="true"></span>
  </button>
  <figcaption>Deploying a static site to the edge — 7 minutes.</figcaption>
</figure>

The alt is deliberately empty: the button's aria-label already carries the meaning, and a duplicate description makes the control noisier to navigate. Include the duration in the label so keyboard and screen-reader users get the same information sighted readers take from the thumbnail.

.video { aspect-ratio: 16 / 9; position: relative; margin: 1.6rem 0; }
.video-facade { position: absolute; inset: 0; width: 100%; height: 100%;
  padding: 0; border: 0; cursor: pointer; background: none; }
.video-facade img { width: 100%; height: 100%; object-fit: cover; border-radius: 0.6rem; }
.video-facade:focus-visible { outline: 3px solid #6a4c93; outline-offset: 3px; }
.video-facade-play { position: absolute; inset: 50% auto auto 50%;
  transform: translate(-50%, -50%); width: 4rem; height: 4rem; border-radius: 50%;
  background: rgba(15, 23, 42, 0.72); }

3. Swap on click, with autoplay

document.querySelectorAll('.video-facade').forEach((btn) => {
  btn.addEventListener('click', () => {
    const frame = document.createElement('iframe');
    frame.src = `https://www.youtube-nocookie.com/embed/${btn.dataset.videoId}?autoplay=1&rel=0`;
    frame.title = btn.getAttribute('aria-label').replace(/^Play video: /, '');
    frame.allow = 'accelerometer; autoplay; encrypted-media; picture-in-picture';
    frame.allowFullscreen = true;
    frame.loading = 'eager';
    btn.replaceWith(frame);
    frame.focus();
  }, { once: true });
});

Three details matter. youtube-nocookie.com avoids setting tracking cookies until playback actually starts. autoplay=1 means the reader presses play once rather than twice. And moving focus to the new iframe keeps keyboard users oriented — without it, focus falls back to the document body and their next Tab starts from the top of the page.

4. Wrap it in a generator shortcode

Do not ask authors to write that markup. In Hugo:

{{/* layouts/shortcodes/video.html — {{< video id="abc123" title="…" dur="7 min" >}} */}}
<figure class="video">
  <button class="video-facade" data-video-id="{{ .Get "id" }}"
          aria-label="Play video: {{ .Get "title" }} ({{ .Get "dur" }})">
    <img src="/img/posters/{{ .Get "id" }}.avif" width="1280" height="720" alt=""
         loading="lazy" decoding="async">
    <span class="video-facade-play" aria-hidden="true"></span>
  </button>
  <figcaption>{{ .Get "title" }} — {{ .Get "dur" }}.</figcaption>
</figure>

Astro and Eleventy equivalents are the same markup inside a component or shortcode. Centralising it means a later improvement — a better poster format, a different privacy domain — ships everywhere at once.

A facade changes more than performance. A standard embed contacts the video platform, and in many configurations sets cookies, the moment the page loads — which means the embed is a consent-relevant third party on every page that carries one, whether or not anyone watches. Because the facade contacts nobody until a click, the page starts with no third-party state at all.

Third-party contact with and without a facade Two states. With a standard embed the page load itself contacts the video platform, so consent must be resolved before the page renders the video. With a facade the page load contacts nobody, and the platform is only contacted after the reader clicks play, at which point consent can be requested in context. When the third party is first contacted Page load HTML from your CDN Standard embed platform contacted now Consent needed before the page settles Facade nobody contacted Click → platform consent asked in context
Deferring the contact also defers the consent question to the moment it is relevant, which is both easier to explain to a reader and cheaper to render.

Two practical consequences. If your consent platform currently blocks video embeds until a reader accepts, the facade lets you drop that rule: nothing to block until the click, and the click itself is a reasonable moment to surface the platform's terms. And if you must keep the block, the facade is what makes the blocked state look deliberate — a poster with a play button reads as a video, whereas a suppressed iframe reads as a broken page.

Use youtube-nocookie.com for the swapped-in player regardless. It defers cookie setting until playback begins, so a reader who clicks and then changes their mind leaves no more state behind than one who never clicked.

Measured Impact

Documentation page with one video, mid-tier Android profile, Chrome 4× CPU throttle, fast 3G, median of five runs:

SetupTransferBlocking timeOriginsLCP
Standard iframe embed780 KB310 ms43.4 s
Iframe with loading="lazy"780 KB300 ms42.6 s
Poster facade (this recipe)24 KB2 ms11.9 s
Facade, after the reader clicks804 KB312 ms4n/a
Transfer and blocking time by embed strategy A horizontal bar chart on a shared scale. The standard embed transfers 780 kilobytes with 310 milliseconds blocking. Lazy loading the iframe transfers the same for readers who scroll. The facade transfers 24 kilobytes with 2 milliseconds, and only readers who click pay the full cost. First-load cost by strategy Standard embed every reader 780 KB · 310 ms lazy iframe readers who scroll 780 KB · 300 ms, just later poster facade readers who click 24 KB · 2 ms Shared linear scale · 1.5 s of LCP improvement came from the origins the facade removes
Lazy loading moves the cost; the facade removes it for the roughly 95% of readers on a docs page who never press play.

Analytics on the site measured showed 4.6% of readers on pages with a video pressed play. The facade therefore removed 780 KB from about 95 of every 100 page views, and the 1.5 s LCP improvement came mostly from the three third-party origins that no longer competed for bandwidth during load.

Pitfalls & Rollback

  • A div instead of a button. Not focusable, not announced, not operable by keyboard. This is the most common defect in published facade snippets.
  • Hot-linking the thumbnail. Keeps a third-party connection and usually serves an over-sized JPEG. Fetch and optimise at build time.
  • Forgetting autoplay. Without it the reader presses play twice and the facade feels broken.
  • Losing focus on swap. Call focus() on the new iframe so keyboard navigation continues from the video.
  • Mismatched box. If the facade and the player have different sizes the swap shifts the page — although a swap within 500 ms of a click is excluded from CLS, a slow network can push it past that window.
  • Rollback: the shortcode is one template. Replacing its body with the original iframe restores the previous behaviour on the next build, with no content changes.

Conclusion

A video embed is the largest single third party most content pages carry, and the facade pattern removes it for everyone who does not watch. Fetch the poster at build time, render a real button with a descriptive label, swap on click with autoplay and focus management, and wrap the whole thing in a shortcode so authors never see the markup. Then apply the same tiering to the rest of the page's third parties with Third-Party Script Performance on Static Sites.

FAQ

Does loading equals lazy on the iframe solve this?

Only partly. It delays the request until the element is near the viewport, which helps a page whose video sits far below the fold, but any reader who scrolls still pays the full 780 kilobytes and the player still runs on the main thread. A facade means most readers never pay it at all.

Do I lose analytics from the video platform?

No. The player loads normally once someone clicks, and it reports playback exactly as it would have. What you lose is impression data for readers who never pressed play, which was never a meaningful signal anyway.

Where should the poster image come from?

Download it at build time and serve it from your own domain, optimised and correctly sized. Hot-linking the platform's thumbnail re-introduces a third-party connection, which is most of what the facade was meant to remove.

Is a facade accessible?

It is if you build it as a real button with a descriptive label and a visible focus ring. A div with a click handler is not keyboard operable and gives screen-reader users nothing to act on, which is the most common way this pattern is implemented badly.

Should the video autoplay after the click?

Yes. The reader has just expressed intent, and without autoplay they have to press play twice. Append autoplay=1 to the embed URL and include autoplay in the iframe's allow attribute.