Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

IntersectionObserverEntry: isIntersecting, intersectionRatio, and target

Read whether a target intersects the root, how much of its area intersects, and which element was measured. Distinguish intersection state from threshold crossings.

Version: Current web platform; runtime support varies

Syntax

entry.isIntersecting     // boolean
entry.intersectionRatio // number in [0, 1]
entry.target            // Element

An IntersectionObserverEntry records one target at the time of measurement. The observer callback receives entries asynchronously and may receive several at once. entry.target is the same Element passed to observe(), not the root. All three properties are read-only, but the element itself can still be modified. This is a web platform API, not part of ECMAScript 2024.

entry.isIntersecting is a boolean indicating whether the target intersects the observer's root at that measurement. With the default root: null, the root rectangle is the top-level document's viewport, not the viewport of the iframe containing the target. The iframe's viewport can still clip the computed intersection. true describes a state, not necessarily a transition into it. Under the specification, edges that just touch can count as intersecting even when the intersection area is zero.

entry.intersectionRatio is a number from 0 to 1: the area of intersectionRect divided by the area of the target's boundingClientRect, not by the root's area. If the target rectangle has zero area, the result is 1 when isIntersecting is true and 0 otherwise. The default measurement is geometric; it does not prove that another element isn't covering the target.

After observe(), you get an initial entry even if the target is outside the root. Later entries can result from crossing a threshold in either direction or from a change in isIntersecting; you don't get an entry for every ratio change. threshold: 0.5 sets a notification boundary, whereas entry.intersectionRatio >= 0.5 tests the value in a particular entry.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IntersectionObserverEntry example</title>
</head>
<body>
<script>
(() => {
  const root = document.createElement('div');
  root.style.cssText = 'position:relative;overflow:hidden;width:100px;height:100px';
  const target = document.createElement('div');
  target.style.cssText = 'position:absolute;left:0;top:50px;width:100px;height:100px;background:royalblue';
  root.append(target);
  document.body.append(root);

  let moved = false;
  const observer = new IntersectionObserver((entries) => {
    for (const entry of entries) {
      console.log(`${entry.isIntersecting} ${entry.intersectionRatio} ${entry.target === target}`);
      if (!moved) {
        moved = true;
        target.style.top = '150px';
      } else {
        observer.disconnect();
        root.remove();
      }
    }
  }, { root, threshold: 0.5 });
  observer.observe(target);
})();
</script>
</body>
</html>

Result

true 0.5 true
false 0 true

Save the example as an HTML file and open it in its own tab in a browser that supports the API. Open the developer console and reload the page. The first entry shows that half the target's area intersects the root. The code moves the target completely outside the root, and the second entry shows no intersection. Both entries refer to the same element; after the second, the code stops observing and removes the root.

Related lessons

  • JavaScript · Lesson 37 · Advanced · Version: 4

Sources