Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

The `passive` option in `EventTarget.addEventListener()`

`passive: true` lets a listener receive the event without being able to cancel its default action. Leaving the option out is not always equivalent to passing `false`.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

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

The EventTarget.addEventListener passive option is an optional boolean property of the third-argument object in target.addEventListener(type, listener, options). If the third argument is a bare boolean, it sets only capture, not passive. This is a web-platform DOM API, not an ECMAScript 2024 language feature; check support in your target runtime.

With passive: true, the listener still runs, but calling event.preventDefault() from it has no effect and may produce a console warning. This does not change event propagation. With passive: false, the listener can cancel the default action with preventDefault(), but only if event.cancelable is true.

If you omit passive, the DOM Standard specifies false by default, except for wheel, mousewheel, touchstart, and touchmove listeners registered on Window, Document, document.documentElement, or document.body, where it specifies true. Support for the option itself does not guarantee these defaults: browser versions, including versions of Safari, have differed in when they default to true. Set false explicitly if you need to cancel the action. Use true when you only need to observe input so the browser can start scrolling without waiting for that listener. The scroll event itself is not cancelable.

Registering again on the same target with the same type, callback, and capture value does not update passive. Use removeEventListener() with the matching type, callback, and capture value, then add the listener again. passive is not used to match a listener for removal and does not control its lifetime.

Examples

{
  const target = new EventTarget();
  const type = "passive-demo";
  const listener = (event) => event.preventDefault();

  for (const passive of [true, false]) {
    target.addEventListener(type, listener, { passive });
    const event = new Event(type, { cancelable: true });
    const result = target.dispatchEvent(event);
    console.log(`passive=${passive}, defaultPrevented=${event.defaultPrevented}, dispatchEvent=${result}`);
    target.removeEventListener(type, listener);
  }
}

Result

passive=true, defaultPrevented=false, dispatchEvent=true
passive=false, defaultPrevented=true, dispatchEvent=false

Each iteration dispatches a fresh, cancelable synthetic event. `defaultPrevented` reports whether it was canceled, and `dispatchEvent()` returns `false` only in the iteration in which cancellation succeeds. A browser warning may appear; the example does not measure scroll performance.

Related lessons

  • JavaScript · Lesson 33 · Advanced · Version: 4
  • JavaScript · Lesson 36 · Advanced · Version: 4
  • JavaScript · Lesson 45 · Advanced · Version: 4

Sources