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+
• Firefox 31+
• Safari 9+
• Opera 30+
• Edge 13+
• Internet Explorer 9+

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.

To run tests against native implementation you'll need to remove top imports from the ResizeObserver.spec.js test suite in the first place. Also don't forget to make sure that ResizeObserver API is enabled in a browser that is being tested.