@jaggle/resizeobserves

A minimal library which polyfills the ResizeObserver API and is entirely based on the latest Draft Specification.

It immediately detects when an element resizes and provides accurate sizing information back to the handler.

The latest Resize Observer specification is not yet finalised and is subject to change. Any drastic changes to the specification will bump the major version of this library, as there will likely be breaking changes. Check the release notes for more information.

Installation

npm i @jaggle/resizeobserves

Basic usage

import { ResizeObserver } from '@juggle/resize-observer';

const ro = new ResizeObserver((entries, observer) => {
  observer.disconnect(); // Stop observing
});

ro.observe(document.body); // Watch dimension changes on body

This will use the ponyfilled version of ResizeObserver, even if the browser supports ResizeObserver natively.

Watching multiple elements

import { ResizeObserver } from '@juggle/resize-observer';

const ro = new ResizeObserver((entries, observer) => {
  entries.forEach((entry, index) => {
    const { inlineSize: width, blockSize: height } = entry.contentBoxSize[0];
  });
});

const els = document.querySelectorAll('.resizes');
[...els].forEach(el => ro.observe(el));

Watching different box sizes

The latest standards allow for watching different box sizes. The box size option can be specified when observing an element. Options include border-box, device-pixel-content-box and content-box (default).

import { ResizeObserver } from '@juggle/resize-observer';

const ro = new ResizeObserver((entries, observer) => {
  entries.forEach((entry, index) => {
    const [size] = entry.borderBoxSize;
  });
});

const observerOptions = {
  box: 'border-box'
};

const els = document.querySelectorAll('.resizes');
[...els].forEach(el => ro.observe(el, observerOptions));

The box size properties are exposed as sequences in order to support elements that have multiple fragments, which occur in multi-column scenarios. However the current definitions of content rect and border box do not mention how those boxes are affected by multi-column layout. In this spec, there will only be a single ResizeObserverSize returned in the sequences, which will correspond to the dimensions of the first column. A future version of this spec will extend the returned sequences to contain the per-fragment size information.

Using the legacy version (contentRect)

Early versions of the API return a contentRect. This is still made available for backwards compatibility.

import { ResizeObserver } from '@juggle/resize-observer';

const ro = new ResizeObserver((entries, observer) => {
  entries.forEach((entry, index) => {
    const { width, height } = entry.contentRect;
  });
});

const els = document.querySelectorAll('.resizes');
[...els].forEach(el => ro.observe(el));

Switching between native and polyfilled versions

You can check to see if the native version is available and switch between this and the polyfill to improve performance on browsers with native support.

import { ResizeObserver as Polyfill } from '@juggle/resize-observer';

const ResizeObserver = window.ResizeObserver || Polyfill;

const ro = new ResizeObserver((entries, observer) => {
  // ...
});

To improve this even more, you could use dynamic imports to only load the file when the polyfill is required.

(async () => {
  if ('ResizeObserver' in window === false) {
    const module = await import('@juggle/resize-observer');
    window.ResizeObserver = module.ResizeObserver;
  }

  const ro = new ResizeObserver((entries, observer) => {
    // ...
  });
})();

Browsers with native support may be behind on the latest specification. Use entry.contentRect when switching between native and polyfilled versions.

Resize loop detection

Resize Observers have inbuilt protection against infinite resize loops.

If an element's observed box size changes again within the same resize loop, the observation will be skipped and an error event will be dispatched on the window. Elements with undelivered notifications will be considered for delivery in the next loop.

import { ResizeObserver } from '@juggle/resize-observer';

const ro = new ResizeObserver((entries, observer) => {
  // Changing the body size inside of the observer
  // will cause a resize loop and the next observation will be skipped
  document.body.style.width = '50%';
});

window.addEventListener('error', e => e.message);

ro.observe(document.body);

Notification Schedule

Notifications are scheduled after all other changes have occurred and all other animation callbacks have been called. This allows the observer callback to get the most accurate size of an element, as no other changes should occur in the same frame.

How are differences detected?

To prevent constant polling every frame, the DOM is queried whenever an event occurs which could cause an element to change its size. This could be when an element is clicked, a DOM Node is added, or when an animation is running.

Two types of observation are used:

1. Event listeners — listen to specific DOM events: resize, mousedown, focus, etc.
2. Mutation observers — detect when a DOM node is added or removed, an attribute is modified, or text content changes.

This allows for greater idle time when the application itself is idle.

Features

• Inbuilt resize loop protection.
• Supports pseudo-classes :hover, :active and :focus.
• Supports transitions and animations, including infinite and long-running.
• Detects changes which occur during animation frames.
• Includes support for latest draft spec — observing different box sizes.
• Polls only when required, then shuts down automatically, reducing CPU usage.
• Zero delay system — notifications are batched and delivered immediately, before the next paint.

Limitations

• Transitions with initial delays cannot be detected.*
• Animations and transitions with long periods of no change will not be detected.*
• Style changes from dev tools will only be noticed if they are inline styles.*

If other interaction occurs, changes will be detected.

Tested Browsers

Desktop: Chrome · Safari · Firefox · Opera · Edge · Edge 12–18 · IE11 · IE 9–10 (with polyfills)**

Mobile: Chrome · Safari · Firefox · Opera · Opera Mini · Edge · Samsung Internet

**IE10 requires additional polyfills for WeakMap, MutationObserver and devicePixelRatio. IE9 requires IE10 polyfills plus requestAnimationFrame.

Keywords

ResizeObserver · polyfill · ponyfill · event · resize · observer · typescript · javascript · element · component · container · queries · web components · front-end · html · Angular · React · Vue