Let’s say you want to track when an element in your DOM enters the visible viewport. You might want to do this so you can lazy-load images just in time or because you need to know if the user is actually looking at a certain ad banner. You can do that by hooking up the scroll event or by using a periodic timer and calling getBoundingClientRect() on that element. This approach, however, is painfully slow as each call to getBoundingClientRect() forces the browser to re-layout the entire page and will introduce considerable jank to your website. Matters get close to impossible when you know your site is being loaded inside an iframe and you want to know when the user can see an element. The Single Origin Model and the browser won’t let you access any data from the web page that contains the iframe. This is a common problem for ads for example, that are frequently loaded using iframes.

Making this visibility test more efficient is what IntersectionObserver was designed for, and it’s landed in Chrome 51 (which is, as of this writing, the beta release). IntersectionObservers let you know when an observed element enters or exits the browser’s viewport.

How to Create an IntersectionObserver

The API is rather small, and best described using an example:

var io = new IntersectionObserver(
	entries => {
		console.log(entries);
	},
	{
		/* Using default options. Details below */
	}
);
// Start observing an element
io.observe(element);

// Stop observing an element
// io.unobserve(element);

// Disable entire IntersectionObserver
// io.disconnect();

Using the default options for IntersectionObserver, your callback will be called both when the element comes partially into view and when it completely leaves the viewport.

If you need to observe multiple elements, it is both possible and advised to observe multiple elements using the same IntersectionObserver instance by calling observe() multiple times.

An entries parameter is passed to your callback which is an array of IntersectionObserverEntry objects. Each such object contains updated intersection data for one of your observed elements.

🔽[IntersectionObserverEntry]
    time: 3893.92
  🔽rootBounds: ClientRect
      bottom: 920
      height: 1024
      left: 0
      right: 1024
      top: 0
      width: 920
  🔽boundingClientRect: ClientRect
    // ...
  🔽intersectionRect: ClientRect
    // ...
    intersectionRatio: 0.54
  🔽target: div#observee
    // ...

rootBounds is the result of calling getBoundingClientRect() on the root element, which is the viewport by default. boundingClientRect is the result of getBoundingClientRect() called on the observed element. intersectionRect is the intersection of these two rectangles and effectively tells you which part of the observed element is visible. intersectionRatio is closely related, and tells you how much of the element is visible. With this info at your disposal, you are now able to implement features like just-in-time loading of assets before they become visible on screen. Efficiently.

IntersectionObservers deliver their data asynchronously, and your callback code will run in the main thread. Additionally, [the spec actually says that IntersectionObserver implementations should use requestIdleCallback(). This means that the call to your provided callback is low priority and will be made by the browser during idle time. This is a conscious design decision.

Scrolling divs

I am not a big fan of scrolling inside an element, but I am not here to judge, and neither are IntersectionObservers. The options object takes a root option that lets you define an alternative to the viewport as your root. It is important to keep in mind that root needs to be an ancestor of all the observed elements.

Intersect all the Things!

No! Bad developer! That’s not mindful usage of your user’s CPU cycles. Let’s think about an infinite scroller as an example: In that scenario, it is definitely advisable to add sentinels to the DOM and observe (and recycle!) those. You should add a sentinel close to the last item in the infinite scroller. When that sentinel comes into view, you can use the callback to load data, create the next items, attach them to the DOM and reposition the sentinel accordingly. If you properly recycle the sentinel, no additional call to observe() is needed. The IntersectionObserver keeps working.

Moar Updates, Please

As mentioned earlier, the callback will be triggered a single time when the observed element comes partially into view and another time when it has left the viewport. This way IntersectionObserver gives you an answer to the question, “Is element X in view?”. In some use cases, however, that might not be enough.

That’s where the threshold option comes into play. It allows you to define an array of intersectionRatio thresholds. Your callback will be called every time intersectionRatio crosses one of these values. The default value for threshold is [0], which explains the default behavior. If we change threshold to [0, 0.25, 0.5, 0.75, 1], we will get notified every time an additional quarter of the element becomes visible:

Any Other Options?

As of now, there’s only one additional option to the ones listed above. rootMargin allows you to specify the margins for the root, effectively allowing you to either grow or shrink the area used for intersections. These margins are specified using a CSS-style string, á la “10px 20px 30px 40px”, specifying top, right, bottom and left margin respectively. To summarize, the IntersectionObservers options struct offers the following options:

new IntersectionObserver(entries => {/* … */}, {
  // The root to use for intersection.
  // If not provided, use the top-level document’s viewport.
  root = null;
  // Same as margin, can be 1, 2, 3 or 4 components, possibly negative lengths.  
  // If an explicit root element is specified, components may be percentages of the
  // root element size.  If no explicit root element is specified, using a percentage
  // is an error.
  rootMargin = "0px";
  // Threshold(s) at which to trigger callback, specified as a ratio, or list of
  // ratios, of (visible area / total area) of the observed element (hence all
  // entries must be in the range [0, 1]).  Callback will be invoked when the visible
  // ratio of the observed element crosses a threshold in the list.
  threshold = [0];
});

iframe Magic

IntersectionObservers were designed specifically with ads services and social network widgets in mind, which frequently use iframes and could benefit from knowing whether they are in view. If an iframe observes one of its elements, both scrolling the iframe as well as scrolling the window containing the iframe will trigger the callback at the appropriate times. For the latter case, however, rootBounds will be set to null to avoid leaking data across origins.

What is IntersectionObserver Not About?

Something to keep in mind is that IntersectionObservers are intentionally neither pixel perfect nor low latency. Using them to implement endeavours like scroll-dependent animations are bound to fail, as the data will be – strictly speaking – out of date by the time you’ll get to use it. The explainer has more details about the original use cases for IntersectionObserver.

How Much Work Can I Do in the Callback?

Short’n’Sweet: Spending too much time in the callback will make your app lag – all the common practices apply.

Go Forth and Intersect thy Elements

The browser support for IntersectionObservers is still fairly slim, so it won’t work everywhere right off the bat just yet. In the meantime, a polyfill is being worked on in the WICG’s repository. Obviously, you won’t get the performance benefits using that polyfill that a native implementation would give you.

You can start using IntersectionObservers right now in Chrome Canary! Tell us what you came up with.