add-eventlistener-with-options

A utility function to check if EventTarget.addEventListener supports adding passive (or capture, once) event options.

Build status

Story behind Passive event listeners

Passive event listeners are a new feature in the DOM spec that enable developers to opt-in to better scroll performance by eliminating the need for scrolling to block on touch and wheel event listeners. Developers can annotate touch and wheel listeners with {passive: true} to indicate that they will never invoke preventDefault. This feature shipped in Chrome 51, Firefox 49 and landed in WebKit. Check out the video below for a side-by-side of passive event listeners in action:

The problem

Smooth scrolling performance is essential to a good experience on the web, especially on touch-based devices. All modern browsers have a threaded scrolling feature to permit scrolling to run smoothly even when expensive JavaScript is running, but this optimization is partially defeated by the need to wait for the results of any touchstart and touchmove handlers, which may prevent the scroll entirely by calling preventDefault() on the event. While there are particular scenarios where an author may indeed want to prevent scrolling, analysis indicates that the majority of touch event handlers on the web never actually call preventDefault(), so browsers often block scrolling unneccesarily. For instance, in Chrome for Android 80% of the touch events that block scrolling never actually prevent it. 10% of these events add more than 100ms of delay to the start of scrolling, and a catastrophic delay of at least 500ms occurs in 1% of scrolls.

Solution: the 'passive' option

Now that we have an extensible syntax for specifying options at event handler registration time, we can add a new passive option which declares up-front that the listener will never call preventDefault() on the event. If it does, the user agent will just ignore the request (ideally generating at least a console warning). Eg:

  var supportsPassive; // The logic to check if passive option is supported in this browser;

  addEventListener(document, "touchstart", function(e) {
    console.log(e.defaultPrevented);  // will be false
    e.preventDefault();   // does nothing since the listener is passive
    console.log(e.defaultPrevented);  // still false
  }, supportsPassive ? {passive: true} : false);

Now rather than having to block scrolling whenever there are any touch or wheel listener, the browser only needs to do this when there are non-passive listeners (see TouchEvents spec). passive listeners are free of performance side-effects.

Reason

This package provides a smooth fallback implementation to use the { passive: true } option in newer browsers, while falling back to false in older ones

Usage

• To add passive event listeners

addEventListenerWithOptions(window, 'touchstart', () => {
    // Do stuff
});

There is a video showing the comparison on CNN website here

Reference and Credits

Most of the story behind implementing this comes from the Web Platform Incubator Community Group suggestion on EventListenerOptions