Autoplaying Video Only When in Viewport

The feature is four lines of observer code and about thirty lines of everything else. This page is the everything else, in the order it has to happen.

Problem / Scenario Context

A landing page has three short muted loops, one per section. The requirement is simple: play when the reader reaches a section, stop when they leave. The first implementation is equally simple:

new IntersectionObserver(([entry]) => {
  const video = entry.target as HTMLVideoElement;
  entry.isIntersecting ? video.play() : video.pause();
}).observe(video);

It works on the developer's machine and then produces three separate production reports: nothing plays on some phones, the console fills with AbortError on fast scrolls, and a reader with reduced motion enabled sees all three loops start anyway. Each of those is a different missing piece, and none of them is in the observer.

Mechanics Explanation

Three independent systems have to agree before a frame is decoded.

The autoplay policy. Browsers permit unprompted playback only for media that is muted; on mobile they additionally require playsinline, or the video is taken fullscreen instead. When either is missing, play() returns a promise that rejects with NotAllowedError — visibility is irrelevant.

The play() promise. play() is asynchronous because the browser may need to decode a first frame. Calling pause() while that promise is pending rejects it with AbortError. A scroll fast enough to enter and leave within a few hundred milliseconds does exactly that, which is why the error appears in the field and never during development.

The reader's motion preference. prefers-reduced-motion: reduce is a request not to animate. Video that starts by itself is unrequested motion, and honouring the preference means not starting it at all rather than starting it more gently.

Comparison Table: Threshold Choice

Using two thresholds — a higher one to start and a lower one to stop — gives hysteresis and stops a video toggling while the reader hovers near the boundary. threshold: [0.35, 0.5] with a play test of >= 0.5 and a pause test of < 0.35 costs nothing and removes the flicker.

Minimal Reproducible Example

<!-- Missing muted: play() rejects and nothing ever runs -->
<video src="/loop.mp4" loop playsinline></video>

new IntersectionObserver(([e]) => {
  const v = e.target as HTMLVideoElement;
  e.isIntersecting ? v.play() : v.pause();     // un-awaited: AbortError on a fast scroll
}, { threshold: 0 }).observe(video);           // threshold 0: starts at the screen edge

Production-Safe Solution

<video class="js-vp-video"
       muted playsinline loop preload="none"
       poster="/loop-poster.jpg" width="960" height="540">
  <source src="/loop.webm" type="video/webm">
  <source src="/loop.mp4"  type="video/mp4">
</video>

const reduce = matchMedia('(prefers-reduced-motion: reduce)');
const pending = new WeakMap<HTMLVideoElement, Promise<void>>();

async function setPlaying(video: HTMLVideoElement, wanted: boolean): Promise<void> {
  const allowed = wanted && !reduce.matches && document.visibilityState === 'visible';
  if (allowed === !video.paused) return;                    // already correct

  if (allowed) {
    const p = video.play();
    pending.set(video, p);
    try { await p; }
    catch (err) {
      if ((err as DOMException).name !== 'AbortError') video.controls = true;  // policy refused
    }
    finally { pending.delete(video); }
  } else {
    const p = pending.get(video);
    if (p) await p.catch(() => {});                         // never pause a pending play
    video.pause();
  }
}

const observer = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    const video = entry.target as HTMLVideoElement;
    if (entry.intersectionRatio >= 0.5) void setPlaying(video, true);
    else if (entry.intersectionRatio < 0.35) void setPlaying(video, false);
  }
}, { threshold: [0.35, 0.5] });

const videos = [...document.querySelectorAll<HTMLVideoElement>('.js-vp-video')];
videos.forEach((v) => observer.observe(v));

// the two signals the observer cannot see
const resync = () => videos.forEach((v) => void setPlaying(v, !v.paused));
document.addEventListener('visibilitychange', () =>
  videos.forEach((v) => { if (document.visibilityState !== 'visible') void setPlaying(v, false); }));
reduce.addEventListener('change', resync);

One shared observer for every video on the page, per the pooling rationale, and a WeakMap holding the pending promise so a removed element does not retain it.

Verification Steps

• Check the promise path: scroll rapidly past a video ten times with the console open; there should be no AbortError.
• Check the policy path: remove muted in DevTools and confirm the code reveals controls rather than failing silently.
• Check the motion preference: enable reduce-motion at the OS level with the page open; playback should stop without a reload.
• Check the tab path: start playback, switch tabs, and confirm in the Network panel that transfer stops.
• Check on a real phone: low-power mode is the one condition that cannot be emulated, and it is the most common field failure.

Common Mistakes to Avoid

• Setting muted from JavaScript after creating the element. The policy is evaluated against the element's state at the time of the request; put it in the markup.
• Using threshold: 0. A video that starts when one pixel is visible will start and stop repeatedly on any scroll past it.
• Ignoring preload. Without preload="none" every video on the page starts downloading before anyone scrolls, competing with the LCP image.
• Retrying a rejected play(). On iOS low-power mode the retry loop drains the battery the mode exists to preserve. Show controls and stop.

FAQ

Related

• Pausing Background Video to Save Battery — what the pause branch is actually saving
• Measuring Video View Time with IntersectionObserver — turning playback into a reportable metric
• Media Playback Visibility Control — the full gate this page implements

↑ Back to Media Playback Visibility Control