@juggle/resize-observer

What is @juggle/resize-observer?

The @juggle/resize-observer package is a polyfill for the ResizeObserver API, which allows developers to observe changes to the size of DOM elements and react accordingly. It provides a way to receive notifications when an element's content rectangle has changed its size, which is useful for responsive designs and element-specific layout updates.

What are @juggle/resize-observer's main functionalities?

Observing size changes in elements

This feature allows you to create a new ResizeObserver instance and observe size changes in DOM elements. When a change is detected, the callback function is executed with the new size information.

const resizeObserver = new ResizeObserver(entries => {
  for (let entry of entries) {
    console.log('Size changed:', entry.contentRect);
  }
});

resizeObserver.observe(document.querySelector('.resizable-element'));

Unobserving elements

This feature allows you to stop observing size changes in a DOM element that was previously being observed by the ResizeObserver instance.

resizeObserver.unobserve(document.querySelector('.resizable-element'));

Disconnecting the observer

This feature allows you to completely disconnect the ResizeObserver instance, which stops observing all elements and clears its references, allowing for garbage collection.

resizeObserver.disconnect();

Other packages similar to @juggle/resize-observer

resize-observer-polyfill

This package is another polyfill for the ResizeObserver API, similar to @juggle/resize-observer. It provides the same basic functionality, allowing developers to observe changes in the size of DOM elements.

react-resize-detector

This package is specifically designed for React and provides components and hooks to listen to resize events on DOM elements. It's a higher-level abstraction compared to @juggle/resize-observer, which is more general-purpose and not tied to a specific framework.

README

ResizeObserver

A ponyfill/polyfill entirely based on the current ResizeObserver Draft Specification.

This library observes elements and dispatches notifications when their dimensions change. Differences are only calculated during animation, or, after DOM mutation or user interaction has occurred, keeping CPU and power consumption minimal.

Installation

npm i @juggle/resize-observer

Usage

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

const ro = new ResizeObserver((entries, observer) => {
  console.log('Body has resized!');
  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.

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 porformance on browsers with native support.

import ResizeObserverPolyfill from '@juggle/resize-observer';

const ResizeObserver = window.ResizeObserver || ResizeObserverPolyfill;

// Uses native or polyfill, depending on browser support
const ro = new ResizeObserver((entries, observer) => {
  console.log('Something has resized!');
});

TypeScript Support

This library is written in TypeScript, however, it's compiled into JavaScript during release. Definition files are included in the package and should be picked up automatically to re-enable support in TypeScript projects.

Limitations

• No support for IE10 and below. IE11 is supported.
• Dynamic stylesheet changes may not be noticed and updates will occur on the next user interaction.
• Currently no support for observations when display:none is toggled (coming soon).