Intersection Observer

Efficiently detect when elements enter or leave the viewport — lazy loading images, scroll animations, infinite scroll, and sticky headers.

What it is, in plain English: The Intersection Observer API lets you observe when one element intersects with another (or with the viewport). Instead of listening to scroll events and measuring element positions (slow and janky), you declare what you want to watch and a callback fires only when visibility changes. This is how lazy loading, scroll-triggered animations, and infinite scroll are built in modern JavaScript.

Where this bites you

observe() reports the element's state straight away. As soon as you start watching an element, the callback fires once with its current visibility, and for anything below the fold that's isIntersecting: false. Code that treats "not intersecting" as "the user scrolled away" (pausing a video, logging an analytics event, unloading content) runs on page load, for things the user never saw.

// #promo sits far below the fold
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (!entry.isIntersecting) {
      console.log("user scrolled away from", entry.target.id);   // e.g. pause a video, send analytics
    } else {
      console.log("visible:", entry.target.id);
    }
  });
});
observer.observe(document.querySelector("#promo"));
// on load, before any scrolling:
// user scrolled away from promo     <- the user never saw it
// (scroll down, then back up)
// visible: promo
// user scrolled away from promo

Watch elements — without scroll events

The old way to detect if something is visible — listening to the scroll event and calling getBoundingClientRect() every pixel — fires hundreds of times per second and forces layout recalculation each time. Intersection Observer does the same thing as part of the browser's own rendering work, and fires only when visibility actually changes.

Basic usage

// Create an observer with a callback and options:
const observer = new IntersectionObserver((entries) => {
  // 'entries' = array of elements whose visibility changed
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      console.log(entry.target, "is now visible!");
    } else {
      console.log(entry.target, "is now hidden");
    }
  });
}, {
  threshold: 0.1,  // fire when 10% of element is visible
});

// Watch elements:
const section = document.querySelector("#hero");
observer.observe(section);

// Stop watching:
observer.unobserve(section);

// Stop all observations:
observer.disconnect();

The basic example above logs "is now hidden" on load for the same reason. That's harmless for logging, but not for real actions. Only treat "not intersecting" as leaving once the element has actually been visible:

const seen = new WeakSet();                       // elements that have actually been on screen

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      seen.add(entry.target);
      console.log("visible:", entry.target.id);
    } else if (seen.has(entry.target)) {          // ignore the initial "not visible" report
      console.log("user scrolled away from", entry.target.id);
    }
  });
});
observer.observe(document.querySelector("#promo"));
// on load: nothing
// visible: promo
// user scrolled away from promo

Lazy loading images (the main use case)

<!-- HTML: use data-src instead of src (placeholder prevents layout shift): -->
<img class="lazy" data-src="/real-image.jpg" src="/placeholder.jpg" alt="...">

// JavaScript: load the real image when it's about to enter the viewport:
const imgObserver = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (!entry.isIntersecting) return;  // skip if not visible

    const img = entry.target;
    img.src = img.dataset.src;       // swap to real URL
    img.classList.remove("lazy");
    imgObserver.unobserve(img);      // done — stop watching this image
  });
}, {
  rootMargin: "200px 0px",  // start loading 200px BEFORE the image enters viewport
});

// Watch all lazy images:
document.querySelectorAll("img.lazy").forEach(img => imgObserver.observe(img));

Scroll animations

/* CSS: elements start invisible */
.fade-in {
  opacity: 0;
  transform: translateY(30px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}
.fade-in.visible {
  opacity: 1;
  transform: translateY(0);
}

// JavaScript: add class when element enters viewport
const animObserver = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      entry.target.classList.add("visible");
      animObserver.unobserve(entry.target);  // animate only once
    }
  });
}, { threshold: 0.15 });

document.querySelectorAll(".fade-in").forEach(el => animObserver.observe(el));

Try It Yourself

// IntersectionObserver — detect when elements enter/leave the viewport
// Best alternative to listening to scroll events

// Basic usage:
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    console.log({
      element:  entry.target.tagName,
      visible:  entry.isIntersecting,
      ratio:    entry.intersectionRatio.toFixed(2),
    });
  });
}, {
  threshold: 0.5,  // fire when 50% of element is visible
});

// In a real page: observer.observe(document.querySelector(".target"));

// Lazy image loading pattern:
function lazyLoadImages() {
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const img = entry.target;
        img.src = img.dataset.src;  // swap placeholder for real URL
        img.classList.remove("lazy");
        observer.unobserve(img);    // stop watching once loaded
      }
    });
  }, { rootMargin: "100px" });  // load 100px before entering viewport

document.querySelectorAll("img[data-src]").forEach(img => observer.observe(img));
}

// Scroll animation pattern:
function animateOnScroll() {
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        entry.target.classList.add("visible");  // trigger CSS animation
        observer.unobserve(entry.target);       // animate once only
      }
    });
  }, { threshold: 0.15 });  // 15% visible triggers animation

document.querySelectorAll(".animate").forEach(el => observer.observe(el));
}

// Infinite scroll — load more when reaching the bottom:
function infiniteScroll(loadMore) {
  const sentinel = document.querySelector(".sentinel");  // empty div at bottom

const observer = new IntersectionObserver(([entry]) => {
    if (entry.isIntersecting) loadMore();
  });

observer.observe(sentinel);
  return () => observer.disconnect();  // cleanup function
}

console.log("IntersectionObserver patterns ready");
console.log("Thresholds: 0 = any pixel, 0.5 = 50%, 1.0 = fully visible");
console.log("rootMargin: adds buffer around viewport (like CSS margin)");

Infinite scroll, sticky headers, and thresholds

Infinite scroll

// Put a sentinel element at the bottom of your list:
// <div class="sentinel"></div>

let loading = false;
let page    = 1;

const sentinel = document.querySelector(".sentinel");

const infiniteObserver = new IntersectionObserver(async ([entry]) => {
  if (!entry.isIntersecting || loading) return;

  loading = true;
  page++;

  const newItems = await fetchPage(page);
  appendItems(newItems);

  if (newItems.length === 0) {
    infiniteObserver.disconnect();  // no more pages
  }

  loading = false;
});

infiniteObserver.observe(sentinel);

Multiple thresholds — track how visible something is

// Fire the callback at multiple visibility percentages:
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    const ratio = entry.intersectionRatio;
    // Animate based on how visible the element is:
    entry.target.style.opacity    = ratio;
    entry.target.style.transform  = `scale(${0.8 + ratio * 0.2})`;
  });
}, {
  threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0],
  // Fires at every 10% change
});

rootMargin — expand/shrink the observation area

const observer = new IntersectionObserver(callback, {
  rootMargin: "100px 0px -50px 0px",
  // Same format as CSS margin: top right bottom left
  // Positive = expand the "viewport" (load earlier)
  // Negative = shrink (only fire when deeper in viewport)
});

// Use cases:
// "200px 0px"   — load images 200px before they reach viewport
// "0px 0px -100px" — don't trigger until element is 100px INTO the viewport

rootElement, spec internals, and ResizeObserver

Custom root element

// By default, root = viewport.
// Can observe relative to a scrollable container:
const scrollContainer = document.querySelector(".scroll-list");

const observer = new IntersectionObserver(callback, {
  root:       scrollContainer,  // observe relative to this element
  rootMargin: "0px",
  threshold:  0.5,
});

MutationObserver and ResizeObserver — the Observer family

// MutationObserver — watch DOM changes:
const mutObserver = new MutationObserver((mutations) => {
  mutations.forEach(m => {
    if (m.type === "childList") console.log("Children added/removed");
    if (m.type === "attributes") console.log("Attribute changed:", m.attributeName);
  });
});
mutObserver.observe(element, { childList: true, attributes: true, subtree: true });

// ResizeObserver — watch element size changes:
const resObserver = new ResizeObserver((entries) => {
  entries.forEach(({ target, contentRect }) => {
    console.log(`${target.id}: ${contentRect.width}x${contentRect.height}`);
  });
});
resObserver.observe(document.querySelector(".responsive-box"));

IntersectionObserver spec (W3C)

IntersectionObserver is specified by the W3C Intersection Observer spec. The browser calculates intersections as a step of its rendering update (after layout) and then queues a task to run the callbacks — they are not microtasks, and they never run inside scroll events. The intersectionRatio is the ratio of intersectionRect area to boundingClientRect area. rootMargin is applied to the root bounds before intersection calculation.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.