Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

Passive event listeners

Reference for the passive option of addEventListener(): why touch and wheel listeners should be passive, what preventDefault() does in them and when to opt out.

A passive listener is a promise to the browser: "this handler will never call preventDefault()". You make a listener passive with the option { passive: true }.

The promise matters for scrolling. Before the browser can scroll the page in response to a touch or wheel gesture, it normally has to wait for your touchstart, touchmove or wheel listeners to finish, in case one of them cancels the scroll. Slow handlers therefore make scrolling feel janky. A passive listener lets the browser scroll immediately, in parallel.

JavaScript
document.addEventListener("touchmove", onMove, { passive: true });
document.addEventListener("wheel", onWheel, { passive: false }); // I really do cancel

Try it

preventDefault() is ignored in a passive listener
Passive or not: does the wheel still scroll?

Syntax

JavaScript
target.addEventListener(type, listener, { passive: true });
target.addEventListener(type, listener, { passive: false });

The passive option is a boolean in the options object of addEventListener(). If you omit it, the default is false, except for touchstart, touchmove, wheel and mousewheel listeners registered on window, document or document.body, where browsers use true.

Usage notes

  • preventDefault() becomes a no-op. The call does nothing in a passive listener, and the console shows a warning such as "Unable to preventDefault inside passive event listener". event.defaultPrevented stays false.
  • Use { passive: true } for scroll-related listeners that only observe (for example tracking touch positions or wheel direction). It is a free performance gain.
  • Use { passive: false } only when you must cancel, for example a canvas that handles wheel as zoom or a custom swipe gesture. Prefer CSS where possible: touch-action: none or overscroll-behavior replace most uses of canceling touchmove.
  • Removing. removeEventListener() matches a listener by type, callback and the capture flag only. passive is not part of the match, so you cannot remove one and keep the other.
  • Other events. The option is accepted for any event, but it only changes behavior where cancelling means something. Making a click listener passive just stops it from preventing the click's default action.
  • Feature detection is not needed any more. Old guides show a trick to detect support for the options object. Every current browser supports it.
  • Frameworks. Some frameworks add .passive modifiers (for example in templates); they just set this option.
  • Lint tools warn about touch and wheel listeners that are not passive. Fix it, or document why you need passive: false.

Browser support

The passive option is supported in all current browsers. The "passive by default on window, document and body" rule is also in all major engines, but treat it as a browser behavior and set the option explicitly when it matters.