addEventListener in Depth — Options & Optimization

Technical Deep Dive & Specifications

Signature & Configuration Dictionary

target.addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;

interface AddEventListenerOptions {
  capture?: boolean;  // If true, fires in Capturing Phase (default: false)
  once?: boolean;     // If true, automatically invoked at most once then removed (default: false)
  passive?: boolean;  // If true, guarantees preventDefault() will NEVER be called (default: false*)
  signal?: AbortSignal; // Listener is automatically removed when the given AbortSignal aborts
}

The Four Core Options Explained

1. capture: boolean

• When true, listener executes during Phase 1 (Descent / Capturing).
• When false (default), listener executes during Phase 3 (Ascent / Bubbling).

2. once: boolean

• When true, the browser automatically removes the listener from the event target's listener list immediately before invoking the callback.
• Eliminates the need to maintain named function references just to call removeEventListener.
• Ideal for transitionend, animationend, dialog initialization, or single-use setup triggers.

3. passive: boolean — The Scroll Performance Secret

• The Compositor Thread Problem: On mobile devices, smooth 60fps / 120fps touch scrolling is handled on a dedicated background Compositor Thread on the GPU. However, when a touchstart or wheel listener is registered, the compositor thread must pause and wait for the Main JavaScript Thread to finish running the listener to see if event.preventDefault() is invoked.
• The Solution: Setting passive: true informs the browser engine: "This listener will only observe the event; it will never prevent default scrolling." The compositor thread immediately initiates scrolling without waiting for the JS thread!
• Default Browsers Behavior: Modern Chrome, Safari, and Firefox default passive: true for touchstart and touchmove events on window, document, and body.

WITHOUT PASSIVE (Jank):
[User Swipes] ──> [Main Thread JS Runs Event Handler...] ──> [Compositor Scrolls Screen] (Delayed 100ms)

WITH PASSIVE (60/120fps Smooth):
[User Swipes] ──> [Compositor Scrolls Screen Immediately (GPU)]
             └──> [Main Thread JS Observes Event Concurrently (Telemetry/Analytics)]

⚠️ Warning: If you call e.preventDefault() inside a listener registered with { passive: true }, the browser ignores the call and generates a console warning: [Intervention] Unable to preventDefault inside passive event listener invocation.

4. signal: AbortSignal

• Links the listener lifecycle to an AbortController.
• Calling controller.abort() automatically unbinds the listener.
• Allows tearing down dozens of listeners across disparate DOM nodes with a single method call.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 49–54 (claimBtn.addEventListener(..., { once: true })): When the user clicks the claim button, the callback runs and the browser removes the event listener from internal dispatch queues before returning.
• Lines 57–60 (scrollBox.addEventListener(..., { passive: true })): Informs the browser compositor thread that scrolling will not be cancelled, enabling hardware-accelerated scroll frames without thread stalls.
• Lines 63–70 (new AbortController(), { signal: controller.signal }): Attaches three distinct listeners (mouseenter, mouseleave, click) to trackBtn, all bound to a single AbortSignal.
• Line 72 (controller.abort()): A single invocation instantly removes all three listeners without needing individual removeEventListener calls.

Expected Browser Render Output

• Clicking "Claim 50% Off Token" displays the code and disarms the button. Subsequent clicks do nothing.
• Scrolling inside the box produces real-time scroll updates without UI hitching.
• Clicking "Abort All Listeners" stops mouse enter/leave logs completely.