Embed

2 min readStableBeginner

Embed drops another page into a responsive iframe. YouTube links are rewritten to the no-cookie player before they load, every frame renders inside a sandbox, and the frame-src allowlist in next.config.mjs decides which hosts a browser will load at all. Widen that list when you need a host it doesn't cover yet.

Quick Start

One url is all it takes. The frame fills the content width at 16:9.

quick-start.mdx

MDX

<Embed
  url="https://www.youtube.com/watch?v=jNQXAC9IVRw"
  title="Me at the zoo"
/>

Adding Options

title is what a screen reader announces, and aspectRatio swaps the box to 4:3 or 1:1.

aspect-ratio.mdx

MDX

<Embed
  url="https://www.youtube.com/watch?v=jNQXAC9IVRw"
  title="Me at the zoo in a 4:3 frame"
  aspectRatio="4:3"
/>

Advanced

Short youtu.be links and youtube.com/embed/ links get the same treatment, so the square frame below still points at https://www.youtube-nocookie.com/embed/jNQXAC9IVRw. Every frame gets the same sandbox, allow-scripts allow-same-origin allow-popups allow-forms, plus allowfullscreen and an allow list covering accelerometer, autoplay, clipboard-write, encrypted-media, gyroscope, and picture-in-picture, which is what lets a video player go fullscreen or start on its own. allow-same-origin only restores the embedded page's own origin, so it can use its own storage and cookies; it never grants access to this page's origin, since the browser keeps parent and child origin-isolated regardless of sandbox attributes. The real boundary is the Content-Security-Policy frame-src list in next.config.mjs, which only allows 'self', youtube-nocookie.com, github.com, and gist.github.com to load at all — any other URL is blocked by the browser before this component's sandbox setting even applies.

short-link.mdx

MDX

<Embed
  url="https://youtu.be/jNQXAC9IVRw"
  title="The same video from a short link"
  aspectRatio="1:1"
/>

A URL that isn't a YouTube link skips the rewrite and loads exactly as you wrote it. Because frame-src starts with 'self', a route from this same site is one of those URLs — no extra configuration, no absolute origin needed.

same-origin.mdx

MDX

<Embed url="/llms.txt" title="This site's llms.txt index" />

Options

urlstringrequired

The URL to embed. YouTube watch, youtu.be, and youtube.com/embed/ links are rewritten to https://www.youtube-nocookie.com/embed/<id>; every other URL, including a site-relative path such as /llms.txt, loads as written.

titlestringDefault: Embedded content

Accessible iframe title, announced by screen readers. An empty string falls back to the default.

aspectRatiostringDefault: 16:9

Frame shape. 16:9 maps to aspect-video, 4:3 to aspect-4/3, and 1:1 to aspect-square. Any other value leaves the frame with no height class at all, so pick one of the three.

Every frame loads with loading="lazy", so a page full of embeds only fetches the ones a reader scrolls to.

Image Zoom

Was this page helpful?