resize-observer-polyfill

What is resize-observer-polyfill?

The resize-observer-polyfill package provides a polyfill for the ResizeObserver API, which allows you to be notified when an element's content rectangle has changed its size, and thus react accordingly. This is particularly useful for responsive designs and element-specific layout updates.

What are resize-observer-polyfill's main functionalities?

Observing element size changes

This feature allows you to observe changes in the size of an element. The callback function is executed whenever the size of the observed element changes, providing you with the new dimensions and allowing you to perform any necessary adjustments.

var ro = new ResizeObserver(entries => {
  for (let entry of entries) {
    const cr = entry.contentRect;
    console.log('Element:', entry.target);
    console.log(`Element size: ${cr.width}px x ${cr.height}px`);
    console.log(`Element padding: ${cr.top}px ; ${cr.left}px`);
  }
});

ro.observe(document.getElementById('myElement'));

Other packages similar to resize-observer-polyfill

element-resize-detector

element-resize-detector is an npm package that offers a way to detect when an element has been resized. It differs from resize-observer-polyfill in that it uses scroll events and other tricks to detect size changes instead of the native ResizeObserver API, which can be useful for broader browser support.

css-element-queries

css-element-queries provides a way to attach event listeners to elements for various purposes, including element resize detection. It includes a ResizeSensor class that can be used to detect when an element's size changes. This package offers additional functionalities like element query conditions, which go beyond the scope of resize-observer-polyfill.

README

ResizeObserver Polyfill

A polyfill for ResizeObserver API.

Implements event based tracking of changes in the dimensions of elements. Uses MutationsObserver and falls back to an infinite dirty checking cycle if the first one is not supported. Handles long running CSS transitions/animations, attributes and nodes mutations along with changes made by :hover pseudo-class (optional).

Compliant with the spec. Doesn't contain any publicly available methods except for those described in the spec. Size is 3.4kb when minified and gzipped.

Live demo (won't run in IE9).

Installation

From NPM:

npm install --save resize-observer-polyfill

From Bower:

bower install --save resize-observer-polyfill

Or just grab one of the pre-built versions from dist.

Browser Support

Polyfill has been tested and known to work in the following browsers:

• Chrome 40+
• Opera 30+
• Firefox 31+
• Safari 9+
• Edge 13+
• Internet Explorer 11
• Internet Explorer 9-10 (tested in compatibility mode of IE11)

NOTE: Internet Explorer 8 and its earlier versions are not supported.

Usage Examples

If you are using ES6 modules with bundlers like Webpack or JSPM:

import ResizeObserver from 'resize-observer-polyfill';

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

observer.observe(document.body);
// ...

Alternatively you can take a pre-built UMD version.

With AMD:

define([
    'resize-observer-polyfill/dist/ResizeObserver'
], function (ResizeObserver) {
    // ...
});

With CommonJS:

var ResizeObserver = require('resize-observer-polyfill/dist/ResizeObserver');

As a browsers' global object:

<script src="resize-observer-polyfill/dist/ResizeObserver.js"></script>
<script>
    (function () {
        var observer = new ResizeObserver(function () {});
    })();
</script>

Global exports

You can also take a version that always extends browsers' global object.

With ES6 modules:

import 'resize-observer-polyfill/index.global';

const observer = new ResizeObserver(() => {});

With AMD/CommonJS:

require('resize-observer-polyfill/dist/ResizeObserver.global');

Configuration

ResizeObserver class additionally implements following static accessor properties:

idleTimeout

After the mutations of DOM attributes, like class or style, an update cycle will be started which will run either until the dimensions of observed elements keep changing or the idleTimeout is reached. This approach is used to handle transitions and animations.

Default timeout value is 50 milliseconds and you can increase it to match the delay of transitions, e.g. when transition starts with the delay of 500 milliseconds you can set ResizeObserver.idleTimeout = 500 to the corresponding value.

Note that even if transitions don't have a delay it's still better to leave this value as it is.

continuousUpdates

By default possible changes in dimensions of elements caused by CSS :hover class are not tracked. To handle them you can set ResizeObserver.continuousUpdtaes = true which in turn will start a continuous update cycle with an interval of 200 milliseconds (using RAF, of course). Keep in mind that this is going to affect the performance.

NOTE: Changes made to these properties will affect all existing and future instances of ResizeObserver.

Building and testing

First make sure that you have all dependencies installed by running npm install. Then you can execute following tasks either with a gulp CLI or with npm run gulp command.

To make a production build:

gulp build:production

To make a development build of polyfill itself (including sourcemap). Files will be located in tmp folder:

gulp build:dev

To run a code style test:

gulp test:lint

Functional tests for all available browsers that are defined in karma.config.js file:

gulp test:spec

If you want to test some specific browser that is not present in karmas' config file you'll need to run gulp test:spec:manual and then navigate to the http://localhost:9876/debug.html page.

And if you need to run tests against native implementation you'll additionally need to remove top imports from the ResizeObserver.spec.js test suite.