You can install the polyfill via npm or by downloading a zip of this repository:
npm install intersection-observer
Adding the polyfill to your site
The examples below show various ways to add the
<script> tags in the HTML:
Using a module loader (e.g. Browserify or Webpack):
// Require the polyfill before requiring any other modules. require('intersection-observer'); require('./foo.js'); require('./bar.js');
Configuring the polyfill
It's impossible to handle all possible ways a target element could intersect with a root element without resorting to constantly polling the document for intersection changes.
To avoid this extra work and performance penalty, the default configuration of the polyfill optimizes for the most common
IntersectionObserver use cases, which primarily include target elements intersecting with a root element due to:
- User scrolling.
- Resizing the window.
- Changes to the DOM.
All of the above can be handled without polling the DOM.
There are, however, additional use cases that the default configuration will not detect. These include target elements intersecting with a root element due to:
- CSS changes on
- CSS changes due to transitions or animations with a long initial delay.
<textarea>elements that cause other elements to move around.
- Scrolling of non-document elements in browsers that don't support the event capture phase.
If you need to handle any of these use-cases, you can configure the polyfill to poll the document by setting the
POLL_INTERVAL property. This can be set either globally or on a per-instance basis.
Enabling polling for all instance:
To enable polling for all instance, set a value for
POLL_INTERVAL on the
IntersectionObserver.prototype.POLL_INTERVAL = 100; // Time in milliseconds.
Enabling polling for individual instance:
To enable polling on only specific instances, set a
POLL_INTERVAL value on the instance itself:
var io = new IntersectionObserver(callback); io.POLL_INTERVAL = 100; // Time in milliseconds. io.observe(someTargetElement);
POLL_INTERVAL property must be set prior to calling the
.observe method, or the default configuration will be used.
Ignoring DOM changes
You can also choose to not check for intersections when the DOM changes by setting an observer's
USE_MUTATION_OBSERVER property to
false (either globally on the prototype or per-instance)
IntersectionObserver.prototype.USE_MUTATION_OBSERVER = false; // Globally // for an instance var io = new IntersectionObserver(callback); io.USE_MUTATION_OBSERVER = false;
This is recommended in cases where the DOM will update frequently but you know those updates will have no affect on the position or your target elements.
This polyfill does not attempt to report intersections across same-origin
iframe boundaries. While supporting same-origin iframes is technically possible, it would drastically reduce performance. Since most
iframe usage on the web is cross-origin, this polyfill chooses to optimize for performantly handling the most common use cases. (Note: neither this polyfill nor native implementations support reporting intersections across cross-origin
The polyfill has been tested and known to work in the latest version of all browsers.
Legacy support is also possible in very old browsers by including a shim for ES5 as well as the
window.getComputedStyle method. The easiest way to load the IntersectionObserver polyfill and have it work in the widest range of browsers is via polyfill.io, which will automatically include dependencies where necessary:
With these polyfills,
IntersectionObserver has been tested an known to work in the following browsers:
Running the tests
To run the test suite for the
IntersectionObserver polyfill, open the
intersection-observer-test.html page in the browser of your choice.
If you run the tests in a browser that support
IntersectionObserver natively, the tests will be run against the native implementation. If it doesn't the tests will be run against the polyfill.