Video embed

A video embed shows a player from another site, such as YouTube or Vimeo, in the page. It is that site's iframe in a figure, with the caption beneath, the same as an image or a code block. To keep the page light and private, a link with a poster can stand in for the player until the reader asks for it.

A player from another site

Take the embed address the video site gives you and put it in an iframe. In a figure the frame fills the width at 16:9, the shape of most video, so no wrapper or padding trick is needed. title names the frame for a screen reader, loading="lazy" waits until the reader scrolls near it, and allowfullscreen lets the player's full-screen button work.

Big Buck Bunny, © Blender Foundation, CC BY 3.0
<figure>
  <iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"
          title="Big Buck Bunny, a short film by the Blender Foundation"
          loading="lazy"
          allow="encrypted-media; picture-in-picture; fullscreen"
          referrerpolicy="strict-origin-when-cross-origin"
          allowfullscreen></iframe>
  <figcaption>Big Buck Bunny, © Blender Foundation, CC BY 3.0</figcaption>
</figure>
A YouTube player in a figure

The youtube-nocookie.com address is YouTube's own privacy-enhanced embed, which holds off on most tracking until the video is played.

Load on click

A player from another site loads its scripts, fonts and tracking as soon as the frame appears, even if nobody presses play. Instead, show a poster that links to the video, with class="play" to draw a play button over it. Nothing is fetched from the video's site until the reader follows the link.

Play Big Buck Bunny on YouTube
Big Buck Bunny, on YouTube
<figure>
  <a class="play" href="https://www.youtube.com/watch?v=aqz-KE-bpKQ">
    <img src="poster.svg" alt="Play Big Buck Bunny on YouTube"
         width="1280" height="720" loading="lazy">
  </a>
  <figcaption>Big Buck Bunny, on YouTube</figcaption>
</figure>
A poster that links to the video

The image's alt text is the link's name, so it says what following the link does. A small optional script can swap the poster for the player in place when it is clicked. Without the script, the link opens the video on its own site, which always works.

Your own video

A video file you host yourself needs no other site at all: use the browser's own video player, as on the Media page. It sits in the same figure and takes the same caption.

A six-second test pattern, hosted on this site
<figure>
  <video controls preload="metadata" poster="poster.jpg">
    <source src="clip.mp4" type="video/mp4">
    <track kind="captions" src="captions.vtt" srclang="en" label="English">
  </video>
  <figcaption>A six-second test pattern, hosted on this site</figcaption>
</figure>
A self-hosted video in the same figure

Other shapes

For a video that is not 16:9, set its shape inline on the frame. An upright phone video is 9:16; cap its width as well, or it will be taller than the screen. The film here is wide, so the player fits it inside the upright frame with bars above and below.

An upright frame, centred
<figure>
  <iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"
          title="Big Buck Bunny, in an upright frame"
          loading="lazy"
          style="aspect-ratio: 9 / 16; max-width: 360px; margin-inline: auto"></iframe>
  <figcaption>An upright frame, centred</figcaption>
</figure>
A 9:16 frame, capped at 360 pixels wide

Accessibility and privacy

title
Every frame says what is in it, so a screen reader can tell one embed from another.
Captions
Choose videos with captions, and check that the player's captions button works from the keyboard.
No autoplay
Leave autoplay off. Sound and movement the reader did not start can be distressing, and they get in the way of a screen reader.
Privacy
An embedded player tells its site who is reading your page. The poster link above tells it nothing until the reader chooses to watch.