Lazy-load images with IntersectionObserver

Thirty img elements in the markup mean thirty requests, and the browser cannot tell the fifth one from the first. IntersectionObserver supplies the missing fact: whether an element is currently near what the reader can see. Used for a source swap it turns below-the-fold images into requests that start only when the reader is about to need them, and it does that with one observer rather than one scroll handler. The first fragment below is the pending markup this pattern drives; the second is the same card written with the platform’s own attribute, kept in view so the two can be compared rather than assumed.

<ul class="gallery">
  <li class="gallery-card">
    <img
      class="gallery-img"
      src="placeholder-lagoon-32x18.avif"
      data-src="lagoon-800.avif"
      data-srcset="lagoon-400.avif 400w, lagoon-800.avif 800w"
      sizes="(min-width: 60rem) 33rem, 100vw"
      width="800"
      height="450"
      alt="Turquoise lagoon between basalt cliffs"
    >
    <noscript>
      <img
        src="lagoon-800.avif"
        width="800"
        height="450"
        alt="Turquoise lagoon between basalt cliffs"
      >
    </noscript>
  </li>
</ul>

<li class="gallery-card">
  <img
    src="lagoon-800.avif"
    srcset="lagoon-400.avif 400w, lagoon-800.avif 800w"
    sizes="(min-width: 60rem) 33rem, 100vw"
    width="800"
    height="450"
    loading="lazy"
    decoding="async"
    alt="Turquoise lagoon between basalt cliffs"
  >
</li>

const pendingImages = document.querySelectorAll('img[data-src]');

const options = {
  root: null,                 // the viewport, not an inner scroll box
  rootMargin: '200px 0px',    // start the swap one thumb-flick early
  threshold: 0                // one painted pixel is enough to matter
};

function loadNow(img) {
  img.src = img.dataset.src;
  if (img.dataset.srcset) {
    img.srcset = img.dataset.srcset;
  }
  delete img.dataset.src;
  delete img.dataset.srcset;
}

function swapWhenVisible(entries, obs) {
  for (const entry of entries) {
    if (!entry.isIntersecting) {
      continue;                        // left the band again before we acted
    }
    loadNow(entry.target);
    obs.unobserve(entry.target);       // one image, one swap, no further entries
  }
}

// typeof on an undeclared global is safe; constructing on it is not.
const canObserve = typeof IntersectionObserver === 'function';
const observer = canObserve ? new IntersectionObserver(swapWhenVisible, options) : null;

for (const img of pendingImages) {
  if (observer) {
    observer.observe(img);
  } else {
    loadNow(img);                      // no observer: fetch now rather than show nothing
  }
}

Explanation

The observer’s job is to answer one question about many elements at once, and the answer arrives as a list of entries rather than as an event per element. Each entry carries the element in entry.target and the current visibility state in entry.isIntersecting, which is why the loop must read that flag before acting: the callback also reports elements that have left the root, and treating any callback as a load instruction would swap sources for images the reader just scrolled past. threshold: 0 makes the condition as cheap as possible — one pixel of the image inside the expanded root is enough — because a source swap has no visual moment to align to; only the fetch matters. The 200px bottom and top band in rootMargin is what makes the swap look instant: the request starts while the image is still off-screen, so decode is usually finished before the reader can see the box.

Two decisions do the reliability work. obs.unobserve(entry.target) runs in the same pass as the swap, so a loaded image never produces another entry and the observer’s target list shrinks to the images still pending; without it the callback keeps firing for elements that are already done, which is harmless in principle and measurable in practice on a long page. The support check is written as typeof IntersectionObserver === 'function' rather than a window property read because new IntersectionObserver(...) would throw in an engine that lacks it, and the fallback then never runs. The fallback loads everything at once, which is the correct degraded behaviour: a page that ignores the deferral is slower, a page that hides its images is broken. The noscript element in the markup covers the case where script cannot run: while scripting is available its children are never parsed into elements, so that second image issues no request and costs nothing until the reader really has no script.

loading="lazy" is the honest comparison, and it is usually the better tool. It needs no script, no data attribute, no observer, it handles a full srcset on its own, and it works on images added by any code path, while the browser decides the deferral distance per engine and connection — which is a feature for readers and an inconvenience for anyone wanting a tuned band. The observer earns its place where the requirement is more than deferral: keeping a placeholder element in the layout until the real file is ready, starting the fetch at a distance the design picks instead of the engine’s, changing several attributes as one coordinated swap, or running a side effect at the same instant such as starting an animation. If the requirement is only “do not fetch this yet”, write the attribute and skip this code.

The boundary worth testing before shipping is the first screen. Images already intersecting at load are reported in the observer’s first delivery, which happens after layout rather than during parsing, so an observer-driven hero is strictly slower than a plain img — keep the largest above-the-fold image unconditionally loaded and observe only what is below it. Deferral also depends on the element having a box: an image inside a display: none tab reports isIntersecting: false forever, so its request waits until that panel is opened and laid out. And because the observer holds the element rather than the address, nodes created after this script ran must be registered explicitly or they stay placeholders indefinitely.