Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

The ResizeObserver interface

Reference for ResizeObserver: observe element size changes for any reason, read contentRect and box sizes, choose the box model, and avoid resize loops.

A ResizeObserver calls your function whenever the size of an element changes, whatever the cause: the window being resized, a sidebar collapsing, text wrapping differently, a user dragging a resize: both handle or content growing. The window.resize event only fires for the window; this API follows individual elements, which is what component-level responsive design needs.

JavaScript
const observer = new ResizeObserver((entries) => {
  for (const entry of entries) {
    console.log(entry.contentRect.width);
  }
});
observer.observe(element);

Try it

Resize me
Box options and the first callback

Syntax

JavaScript
const observer = new ResizeObserver(callback);
observer.observe(target);
observer.observe(target, { box: "border-box" });
observer.unobserve(target);
observer.disconnect();

Parameters

Name Description
callback(entries, observer) Receives an array of ResizeObserverEntry objects, one per element whose size changed.
target The element to watch.
options.box Which box to watch: "content-box" (default), "border-box" or "device-pixel-content-box".

Entry fields

Field Description
target The observed element.
contentRect A DOMRectReadOnly for the content box (older, still widely used).
contentBoxSize Array with an object { inlineSize, blockSize } for the content box.
borderBoxSize The same, for the border box.
devicePixelContentBoxSize Content box size in device pixels, where supported.

Return value

All methods return undefined.

Usage notes

  • The callback runs once initially. When you call observe(), the browser reports the starting size at the next rendering step, even if nothing changes later. Plan for that first call.
  • Sizes are logical. inlineSize is the width in horizontal writing modes and the height in vertical ones. The size arrays have one item for most elements.
  • Observing is by box. Changing the border or padding of a content-box target does not trigger a callback if the content size stays the same; pick border-box if you care about those.
  • No loops, please. Changing the size of the element you observe from the callback can cause "ResizeObserver loop completed with undelivered notifications" warnings. Change something else, or defer the change with requestAnimationFrame.
  • Not for inline elements. Elements with display: inline have no box size to observe; use block, inline-block, flex or grid items.
  • Prefer CSS where it fits. Container queries (@container) change styles by container size without any JavaScript. Use ResizeObserver when scripts must act, for example redrawing a canvas.
  • Batching. All size changes found in one frame are delivered in one callback invocation.
  • Cleanup. Call unobserve() for removed elements or disconnect() for the whole observer.

Browser support

ResizeObserver is supported in all current browsers. The box option and the size arrays are widely available; devicePixelContentBoxSize is less so, so check a compatibility table.