Observers

Watchers, not loops

Web pages often need to notice when something changes. For example:

• A card scrolls into view.
• A widget from another company adds a new element to the page.
• A box on the page gets wider.
• The browser writes down how long a task took.

You could check for these changes again and again with a timer. This is called polling. Polling wastes work, because most checks find nothing new. It can also check at the wrong moment.

The browser has a better tool: observers. You make an observer and give it a callback. A callback is a function you hand over, so the browser can call it later. Then you tell the observer what to watch. When the thing changes, the browser calls your callback. It passes a list of small objects that describe what changed. Some observers call these objects entries; one calls them records.

Each observer watches one kind of change.

This table lists the four observers in this lesson. Read one row per observer.

The lesson builds each observer with a real lab. Before you choose one, say what kind of change you care about. Then pick the observer that watches that kind of change.

IntersectionObserver tells you when an element moves into or out of an area. The element you watch is the target. The area is the root.

• With root: null, the root is the viewport: the part of the page you can see in the browser window.
• You can also set root to a box on the page that scrolls. Then the root is that box.

"Intersect" means "overlap". The target intersects the root when some part of it is inside the root. Many sites use this to load images only when they come near the screen, to show items as you scroll, and to load more of a long list.

function shouldLoadImage(entry) {
  return entry.isIntersecting ? "load image" : "wait";
}
console.log(shouldLoadImage({ isIntersecting: true }));

Your callback gets one entry for each target that changed. An entry has two useful properties:

• isIntersecting is true when any part of the target is inside the root. Use it for a simple yes-or-no choice.
• intersectionRatio is how much of the target is inside, from 0 (none) to 1 (all). Use it when the amount matters.

Line 2 returns "load image" when the entry is intersecting, and "wait" when it is not. Line 4 passes an entry with isIntersecting: true, so it prints load image.

Three settings matter most:

• threshold says how much of the target must be inside before your callback runs. It is a number from 0 to 1, or a list such as [0, 0.5, 1]. With a list, the callback runs each time the target passes one of those points.
• rootMargin makes the root bigger or smaller, in px or %. A bigger root lets you start loading a little before the target reaches the screen.
• Right after you call observe(), the browser schedules the callback once, before the user scrolls. That first entry tells you where the target is now.

The next example is for an endless list. At the bottom of the list sits a small, empty element. It is called a sentinel, which means a guard. When the sentinel comes into view, the user has reached the end, so it is time to load the next page of items.

function nextPage(entry, page, loading) {
  if (!entry.isIntersecting || loading) return "wait";
  return "load page " + (page + 1);
}
console.log(nextPage({ isIntersecting: true }, 1, false));

Line 2 returns "wait" if the sentinel can't be seen, or if a page is already loading. The loading check matters. Without it, one visible sentinel could start several requests for the same page before the first one finishes. Line 5 passes a visible sentinel, page 1, and loading set to false, so it prints load page 2.

1const observer = new IntersectionObserver(callback, {2  root: scrollBox,3  threshold: [0, 0.5, 1],4  rootMargin: "40px 0px",5});6observer.observe(card);7observer.observe(sentinel);

In the lab, each card starts as a grey placeholder. When a card comes into the scroll box, the code fills it with a colored block. The sentinel at the bottom adds more cards when it shows. That is an endless list: you watch one small marker instead of working out scroll positions yourself.

A mutation is a change. MutationObserver watches an element, called the target node, and tells you when it changes. It can see three kinds of change:

• children were added or removed;
• an attribute changed, such as class or data-state;
• the text inside changed.

It does not replace normal events like click. If your own code makes the change, you already know about it. Use a MutationObserver when code you didn't write changes the page, or when a tool needs to check changes after they happen.

Each change becomes a record: a MutationRecord object that describes one change. A record for new children has an addedNodes list with the new elements in it.

function addedItemNames(records) {
  return records
    .flatMap((record) => [...record.addedNodes])
    .map((item) => item.textContent);
}
console.log(addedItemNames([{ addedNodes: [{ textContent: "Tea" }] }]));

Line 3 joins the addedNodes of every record into one list. Line 4 keeps only each item's text. Line 6 passes one record with one new item, Tea, so it prints ["Tea"]. In a real list, you may also want to skip things that are not elements.

When you call observe(), you pass an options object. It says which changes become records:

• childList: children added or removed.
• attributes: attribute changes.
• characterData: text changes.
• subtree: watch the children's children too, all the way down, not only the target.
• attributeOldValue: also save the value the attribute had before the change.

You must turn on at least one of childList, attributes, or characterData. If you set attributeOldValue: true and leave out attributes, the browser turns attributes on for you. Text usually sits inside the target's children, so characterData often needs subtree: true to see it. Turn on only what you need: fewer options mean fewer records to read.

Here is the key timing rule. The observer doesn't call you after each change. It saves the records in a list while your script runs. When the script ends, it calls your callback once, with all of the records. The callback runs as a microtask: a small job the browser runs right after the current script ends, before anything else.

1const log = [];Run2log.push("sync: start");3const records = [];4records.push("childList: added item");5records.push("attributes: data-state old=closed");6records.push("characterData: title changed");7log.push("sync: end");8log.push("callback: " + records.length + " records");9console.log(log.join(" | "));

1const log = [];2log.push("sync: start");3const records = [];4records.push("childList: added item");5records.push("attributes: data-state old=closed");6records.push("characterData: title changed");7log.push("sync: end");8log.push("callback: " + records.length + " records");9console.log(log.join(" | "));

You can learn more about this timing in the Microtasks in depth lesson. Two more methods help when you are done:

• takeRecords() gives you the records that are still waiting, right now, and empties the list. The callback won't get those records.
• disconnect() stops the observer. It no longer watches any element, and the callback no longer runs.

A safe way to stop is: call const pending = observer.takeRecords(), handle those records, then call observer.disconnect(). That way, you don't lose changes without noticing.

A part of the page can get narrower even when the browser window stays the same size. For example:

• a sidebar opens next to it;
• its text wraps onto more lines;
• the grid it sits in changes;
• a font finishes loading.

None of these has to fire the window's resize event, because the window didn't change. ResizeObserver watches the element itself. The browser first works out the size and position of everything on the page; this step is called layout. Then it draws the pixels; this is called paint. ResizeObserver calls you after layout and before paint, so the size you read is up to date.

function layoutFor(width) {
  return width < 360 ? "stacked" : "row";
}
console.log(layoutFor(320));

Line 2 returns "stacked" when the width is less than 360, and "row" otherwise. Line 4 passes 320, so it prints stacked. A real component would read the width in the observer, then use this choice to set a class.

1const observer = new ResizeObserver((entries) => {2  for (const entry of entries) {3    console.log(entry.contentRect.width);4    console.log(entry.borderBoxSize?.[0]?.inlineSize);5  }6});7observer.observe(panel, { box: "border-box" });

Each entry can give you the size in two ways:

• contentRect.width is the width of the content box: the inside area, without padding or border. Every browser that has ResizeObserver gives you this.
• borderBoxSize[0].inlineSize is the width of the border box: the content plus padding and border. It is newer, and it is a list, so you read the first item with [0].

By default, the observer watches the content box. You can pass { box: "border-box" } to observe() to watch the border box instead. There is also device-pixel-content-box, but not every browser has it, so check first. Pick the size that fits your layout choice.

In the callback, read the size, then set state or a class. Don't change the size of the element you are watching inside its own callback. That would cause another size change, then another callback, again and again.

The browser keeps a list of timing records called the Performance Timeline. Each record is an entry. There are several kinds, called entry types:

• mark: a named moment in time that you save.
• measure: the time between two marks.
• resource and navigation: how long files and page loads took.
• Some extra types that only some browsers have.

PerformanceObserver calls your callback when new entries are added. The easiest type to start with is measure, because you make it yourself. You call performance.mark() at the start and at the end of a task. Then performance.measure() makes one entry with the time between them.

1const observer = new PerformanceObserver((list) => {2  for (const entry of list.getEntries()) {3    console.log(entry.name + ": " + entry.duration.toFixed(2) + "ms");4  }5});6observer.observe({ type: "measure", buffered: true });7performance.mark("work:start");8// do a small task9performance.mark("work:end");10performance.measure("demo work", "work:start", "work:end");

Not every browser has every entry type. For example, longtask, layout-shift, and largest-contentful-paint are mostly found in Chrome and browsers built on it. Checking what a browser has before you use it is called feature detection. Read PerformanceObserver.supportedEntryTypes once the page has loaded in the browser, and observe only the types in that list.

The names are long, but the choice is short. Ask one question: did something come into view, did the page change, did an element change size, or did the browser record a time? Sort each task below by its answer.

Where you'll use this

Observers help most when the browser already knows the answer, and your code would only be guessing.

Use IntersectionObserver to:

• load images and videos just before they reach the screen;
• highlight a link in a table of contents when its heading comes into view;
• add more rows when a sentinel shows.

Clean up when a job is done. Once an image has loaded, call unobserve(image) to stop watching it, or disconnect() to stop watching everything.

Use MutationObserver where your code meets code you didn't write. Examples are a rich text editor, a widget from another company, or a script that fixes attributes after a library changes the page. Watch the smallest element you can, and turn on only the options you need. Watching the whole page with subtree: true can give you a flood of records.

Use ResizeObserver for parts of the page that change their layout based on their own width. It works well with the Sizes, scrolling & coordinates lesson. You still read real sizes, but the observer tells you when to read them.

Use PerformanceObserver to measure your own code with marks and measures. Use the extra entry types only after feature detection.

The next example counts each article as "seen" only once. It uses a Set: a collection that holds each value at most once. seen.has(id) asks if the id is already there, and seen.add(id) puts it in.

const seen = new Set();
function recordSeen(entry, id) {
  if (entry.isIntersecting && !seen.has(id)) {
    seen.add(id);
    return "seen: " + id;
  }
  return "skip";
}
console.log(recordSeen({ isIntersecting: true }, "article-1"));

Line 3 checks two things: the article can be seen, and its id is not in seen yet. If both are true, line 4 saves the id and line 5 returns "seen: article-1". If the same article leaves and comes back, its id is already in the set, so line 7 returns "skip". Line 9 prints seen: article-1.

Common misconceptions

• “Observers call my callback right away.” They don't. Each one calls it a little later. IntersectionObserver calls it when the browser next checks positions. MutationObserver calls it as a microtask after the script ends. ResizeObserver calls it after layout. PerformanceObserver calls it after new entries are recorded.
• “Threshold 1 means the target can be seen at all.” No. It means the whole target is inside the root. To react when any part comes in, use 0 or a small number.
• “MutationObserver is a click listener.” No. Use events for things the user does. Use mutation records for changes to the page, after they happen.
• “The window's resize event covers every size change.” No. A card can change size while the window stays the same.
• “Every performance entry type works in every browser.” No. Some types only exist in some browsers. Use feature detection.
• “Calling disconnect is optional.” Not on pages that stay open a long time. Without it, old callbacks can keep running, and old elements can stay in memory.

Key takeaways

• Use an observer when the browser can tell you about a change. It does less work than checking again and again with a timer.
• IntersectionObserver watches whether a target is inside a root. threshold can be a list, and rootMargin lets you start loading early.
• MutationObserver saves records of page changes and hands them over in one batch, as a microtask, after the script ends.
• ResizeObserver watches one element's size, after layout and before paint. Don't resize the watched element inside its callback.
• PerformanceObserver watches timing entries. Check supportedEntryTypes before you use the types that only some browsers have.

An observer is a browser watcher with one job: you say what counts as a change, start watching, handle the entries that arrive later, and disconnect when you are done.

Up next: Animation with JavaScript.