ResizeObserver: Browser Support, Features, Known Issues

What is ResizeObserver?

ResizeObserver is a JavaScript interface that reports changes to a DOM element's content box, border box, or device-pixel content box. The W3C CSS Working Group edits the spec, and pages access the API through the global ResizeObserver constructor and its observe, unobserve, and disconnect methods.

Which browsers does ResizeObserver support?

ResizeObserver is available in every modern browser, with global browser support of about 96%. Internet Explorer is the only major browser that never added it, and Opera Mini still has no support either.

What are the key features of ResizeObserver?

ResizeObserver gives a page a callback every time an element's box changes size, with measurements that match the CSS box model rather than the viewport. The API surface is small and follows the same pattern as MutationObserver and IntersectionObserver.

• new ResizeObserver(callback): Creates an observer that fires the callback every time an observed element's size changes. The callback receives an array of ResizeObserverEntry objects and the ResizeObserver instance itself.
• observe(target, options): Starts watching a DOM element or SVG element. The optional options object accepts a box property of content-box, border-box, or device-pixel-content-box.
• unobserve(target): Stops watching one element while leaving the rest of the targets active on the same observer.
• disconnect(): Stops every observation on the observer in one call. Use it when a component unmounts or a route changes.
• ResizeObserverEntry: Reports the new dimensions through contentRect, contentBoxSize, borderBoxSize, devicePixelContentBoxSize, and the target element. Each Size property is an array because writing-mode flips block and inline axes.
• Element-scoped tracking: Reports size changes for any DOM box, not just the viewport. That covers iframes, custom elements, dynamic flex children, and SVG groups.
• Box-model accuracy: Reports the content box, border box, or device-pixel content box, so measurements match what CSS already calculated. No double layout pass is needed.
• Resize-loop guard: The browser fires an error event with the message ResizeObserver loop completed with undelivered notifications when callbacks fight each other. The guard prevents the page from locking up.

What are the common use cases of ResizeObserver?

ResizeObserver shines anywhere a layout has to react to a container's size rather than the viewport's size. Production code uses it for responsive components, scroll preservation, canvas resizing, and runtime layout switches.

• Per-element media queries: Switch a component layout when its parent container crosses a breakpoint. CSS container queries cover most cases, but ResizeObserver still wins when the breakpoint logic depends on JavaScript.
• Chat-window scroll positioning: Pin a conversation to the latest message when the input grows or the window resizes. The observer recalculates scrollTop on every size change so the user never loses context.
• Canvas and WebGL framebuffer resizing: Match the drawing buffer to the canvas element's CSS box. Reading devicePixelContentBoxSize avoids the half-pixel blur that comes from rounding contentRect on high-DPI displays.
• Custom element layout: Notify a Web Component when the host element changes size. Children can re-render columns, virtualized lists, or charts without listening to window.resize.
• Photo grids and masonry layouts: Add or remove tiles to keep the grid full whenever the container width changes. The observer fires once per real size change instead of on every animation frame.
• Flex row to column switch: Reflow a toolbar or card row into a stacked column when the parent narrows. The observer handles the breakpoint inside the component instead of leaking it to a global media query.

How do you check if a browser supports ResizeObserver?

You check ResizeObserver support by feature-testing the global constructor before you call it. The check works on any page and takes about thirty seconds in DevTools.

• Open DevTools: Press F12 or right-click the page and pick Inspect, then switch to the Console tab.
• Test the global: Type typeof ResizeObserver and press Enter. A modern browser prints "function"; an unsupported browser prints "undefined".
• Construct an observer: Run new ResizeObserver(() => ) and confirm no exception fires. The observer constructs synchronously when the API exists.
• Observe an element: Pass an element to the observer with observer.observe(document.body) and resize the window. Each resize logs a callback fire with a ResizeObserverEntry array.
• Plan a fallback: If step 2 prints "undefined", ship the juggle/resize-observer polyfill or fall back to window.resize for the rare visitor on Safari 12 or older.

The same logic fits into a script tag for production. Paste this snippet into the DevTools console of Chrome, Firefox, Safari, or Edge to confirm support and watch live size updates.

// Paste this into the DevTools console to confirm ResizeObserver support
// and watch the .card element react to size changes.
if ("ResizeObserver" in window) {
  console.log("ResizeObserver is available.");

  const card = document.querySelector(".card") || document.body;
  const observer = new ResizeObserver((entries) => {
    for (const entry of entries) {
      const { inlineSize, blockSize } = entry.contentBoxSize[0];
      console.log("card size", Math.round(inlineSize), "x", Math.round(blockSize));
    }
  });

  observer.observe(card);
} else {
  console.log("ResizeObserver is not supported. Fall back to window.resize.");
}

What are the known issues with ResizeObserver?

ResizeObserver has the same coverage gap as most web APIs that arrived after Chrome 64, plus one signature pitfall: the observer callback can trigger another size change that wakes the same callback. Plan around the loop and the test-environment gaps.

• ResizeObserver loop error: Browsers fire an ErrorEvent with the message ResizeObserver loop completed with undelivered notifications when callback work resizes a shallow ancestor. Wrap mutating work in requestAnimationFrame to defer it to the next frame.
• ResizeObserver loop limit exceeded warning: Webpack dev server, Cypress, and a few Chrome extensions surface this message when iframes resize repeatedly. The warning is harmless, but it pollutes logs and can flag false test failures.
• jsdom does not implement ResizeObserver: Jest and Vitest test environments based on jsdom throw ReferenceError: ResizeObserver is not defined in unit tests. Stub the API with a Jest manual mock or import the juggle/resize-observer polyfill in your test setup file.
• Safari 13.0 had ResizeObserver disabled by default: macOS Safari 13.0 shipped the code behind a flag, so the API became reliable from Safari 13.1 on macOS and Safari 13.4 on iOS. Treat anything older as unsupported even if "ResizeObserver" in window returns true.
• contentBoxSize is an array, not an object: Writing-mode flips block and inline axes, so the spec returns ResizeObserverSize entries inside an array. Older code that reads entry.contentBoxSize.inlineSize directly throws TypeError on Firefox 79 and later.
• Worker threads cannot create ResizeObserver: The constructor lives on the Window object only. Pages that need size data inside a Web Worker must postMessage the dimensions from the main thread.
• Internet Explorer never adds support: IE 11 and earlier do not implement ResizeObserver. Sites that still target IE must polyfill the API or fall back to window.resize plus getBoundingClientRect, which costs an extra layout pass.

In my experience, the loop error during Cypress runs is the trickiest one to silence. The fix that has stuck is wrapping every page mutation that lives inside a ResizeObserver callback in requestAnimationFrame, then ignoring the harmless warning in the cypress.config event hook.

Citations

All ResizeObserver version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - ResizeObserver: developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
• MDN Web Docs - Resize Observer API: developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API
• W3C - Resize Observer Working Draft: w3.org/TR/resize-observer
• CSSWG - Resize Observer editor's draft: drafts.csswg.org/resize-observer
• web.dev - ResizeObserver: it's like document.onresize for elements: web.dev/articles/resize-observer
• Chrome Platform Status - ResizeObserver: chromestatus.com/feature/5705346022637568
• Mozilla - Firefox 69 release notes: mozilla.org/en-US/firefox/69.0/releasenotes
• Apple Developer - Safari 13.1 release notes: developer.apple.com/documentation/safari-release-notes/safari-13_1-release-notes
• juggle/resize-observer polyfill: github.com/juggle/resize-observer
• Google Chrome samples - ResizeObserver demo: googlechrome.github.io/samples/resizeobserver
• Microsoft Learn - ResizeObserver in Edge: learn.microsoft.com/en-us/microsoft-edge/web-platform/site-impacting-changes