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.
const observer = new ResizeObserver((entries) => { for (const entry of entries) { console.log(entry.contentRect.width); } }); observer.observe(element);
Try it
Syntax
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.
inlineSizeis 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-boxtarget does not trigger a callback if the content size stays the same; pickborder-boxif 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: inlinehave 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. UseResizeObserverwhen 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 ordisconnect()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.