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.
document.addEventListener("touchmove", onMove, { passive: true }); document.addEventListener("wheel", onWheel, { passive: false }); // I really do cancel
Try it
Syntax
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.defaultPreventedstaysfalse.- 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: noneoroverscroll-behaviorreplace most uses of cancelingtouchmove. - Removing.
removeEventListener()matches a listener by type, callback and thecaptureflag only.passiveis 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
clicklistener 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
.passivemodifiers (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.