YouTube in Your Posts — the Click-to-Play Embed

Astro Rocket includes a YouTube component for embedding YouTube videos in blog posts and pages. It costs the page nothing until the reader presses play: no YouTube JavaScript, no third-party cookies, no Lighthouse impact. This post shows you how to use it and how it works.

How to embed a video

Import the component at the top of your .mdx file, then place it where the video should appear:

import YouTube from '@/components/patterns/YouTube.astro';

<YouTube id="QONgJurkigk" title="NASA" />

• id — the video’s YouTube id: the part after watch?v= in the video’s URL. For https://www.youtube.com/watch?v=QONgJurkigk, the id is QONgJurkigk.
• title — the video’s title. Required, because it’s what screen readers announce for the play button and it becomes the player’s accessible name once loaded.
• class — optional, for extra styling.

That’s everything. The component works in every .mdx blog post and page, in any number of instances per page.

See it work

Here is the component in this post — press play:

Before you clicked, that box was only a thumbnail image and a button. You can verify it in your browser’s developer tools: the page made no request to YouTube at all. The player, its megabyte of JavaScript, and its cookies only arrive when the reader asks for them.

Why not paste YouTube’s iframe?

The embed code from YouTube’s share dialog works in MDX too — but it makes every visitor pay for the video, including all the visitors who never press play:

• ~1 MB of player JavaScript, downloaded and executed on page load;
• third-party cookies from youtube.com, with the consent obligations that come with them;
• a Lighthouse performance hit on what was a 100-scoring page;
• a fixed-size player that doesn’t adapt to the article column.

The component avoids all four.

How it works

1. The page renders a facade. At build time the component outputs the video’s thumbnail (a plain, lazily-loaded image from YouTube’s cookieless image CDN) and a play button. No script, no iframe, no player.
2. Nothing loads until the click. When the reader presses play, the facade is swapped for the real player — served from youtube-nocookie.com, YouTube’s privacy-enhanced domain — with autoplay, so the click that loads the player also starts the video.
3. The play button is a real button. It’s keyboard-operable (Enter works), its label is localized through the theme’s i18n dictionary (English and Dutch ship with the theme), and focus moves to the player after the swap. With JavaScript disabled, a “Watch on YouTube” link is offered instead.
4. No layout shift. The box reserves its 16:9 space up front, so nothing on the page moves when the player arrives.

The result: an article with three videos ships exactly as many YouTube bytes as an article with none — zero.

Self-hosted video files

If the video is your own file rather than a YouTube upload, you don’t need this component. MDX accepts a native <video> tag directly:

<video src="/videos/demo.mp4" controls preload="none" poster="/videos/demo-poster.jpg"></video>

And project galleries accept video slides natively — how those work is covered in the video slides post.

Where it lives

The component is a single file, src/components/patterns/YouTube.astro — no dependencies, no client framework. A live example is on the components page, together with every other pattern component.