Embedding video in your docs and landing pages without slowing them down

A video on a page makes a point faster than three paragraphs. It can also be the slowest thing on the page, if you embed it carelessly.

Here are the habits that keep a page fast.

Why embeds slow pages down

A video player is a small application. When you embed one, the browser loads the player's code, its styles, and often a thumbnail and some metadata before anyone presses play. Put four of them on a page and the cost adds up, even if nobody watches.

The video itself does not load until the viewer plays it, and a good host streams it in adaptive chunks. So the cost you control is the player, not the footage.

Give the embed a fixed size

Set the width and height, or an aspect ratio, so the page does not jump when the player appears. Layout shift is annoying for readers and it counts against your page's loading score.

A 16:9 container that scales with the page width is the usual answer.

One video per section, and not too many per page

One clear video near the top of a landing page, or one per step in a walkthrough, works. A wall of twelve players does not. If a docs page needs many videos, consider a short list of links to video pages instead.

Load the player lazily

If the video is below the fold, load the player when the reader scrolls near it. Many embeds support a lazy loading attribute on the iframe. Add loading="lazy" and the browser will wait.

<iframe
  src="YOUR-EMBED-URL"
  loading="lazy"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen
  style="border: none; width: 100%; aspect-ratio: 16 / 9;"
></iframe>

Use the embed code your host gives you rather than copying this one. The attributes differ by host.

Do not autoplay unless there is a reason

Autoplay with sound is blocked by most browsers. Autoplay without sound can be fine for a short hero loop. For a demo, let the reader press play. It also keeps your minutes streamed down, since only people who want to watch are counted.

Keep videos short and cut the intro

The most useful change is not technical. A 90-second demo gets watched. A five-minute one with a logo animation does not. Trim the start, put the point in the first ten seconds, and say what the video will show.

Check the page on a slow connection

Open the page in your browser's developer tools with the network throttled to a slow connection. If the page is usable before the video loads, you are fine. If it is not, something other than the video is probably too heavy.

Let your agent do the chores

If you host on Modo, you can ask your AI agent to upload the file and give you the embed code, then paste it in. See connecting your AI agent. The result is a standard iframe, so everything above applies to it.