DOM & EventsBaseline · Widely

DOM Event Propagation (Capture, Target, Bubble)

Mental Model

Every DOM event traverses the tree downward (Capture), reaches the originating element (Target), and walks back up to window (Bubble). Delegation attaches a single listener on a shared ancestor and identifies targets via event.target.closest(...).

Interactive Simulator

DOM Click Propagation Lifecycle

Trace the event path from window down to <button> and back up.

window
ul (delegator)
button (target)
Step 1 / 4: 1. Hit-Testing

The engine identifies <button> as event.target at the pointer coordinates.

Internal State / Memory
eventPhase
HIT_TEST
target
<button>
currentTarget
null

Under the Hood

  1. Hit-Testing: The engine identifies the deepest element under the pointer (event.target).
  2. Capture Phase: Walks window -> document -> html -> ... -> parent, invoking listeners registered with { capture: true }.
  3. Target & Bubble Phases: Invokes listeners on target, then walks back up to window (unless bubbles: false, such as focus, blur, or scroll).
  4. Microtask Checkpoint: Between two distinct listeners triggered by a real UI event, the Event Loop drains pending microtasks.
JS
// Single delegated listener handles 1,000 rows without per-row allocations
tableBody.addEventListener('click', (event) => {
  const row = event.target.closest('tr[data-row-id]');
  if (!row) return;
  selectRow(row.dataset.rowId);
});

Problem Genealogy

  • 2000 (Incompatible Netscape/IE Models): Capture-only in Netscape, Bubbling-only in Internet Explorer, forcing every library to ship a bespoke event normalizer.
  • 2002 (DOM Level 2 Events): Unified three-phase model (addEventListener(type, fn, useCapture)).
  • 2015+ (Root Event Delegation in Frameworks): Single listener at the framework root avoiding thousands of per-node listener allocations.

Production Pitfalls

Production Pitfall
  • stopPropagation() breaks analytics and popovers: Halting propagation prevents global listeners (including Popover API light-dismiss or telemetry) from receiving the event.
  • Non-passive touchstart / wheel listeners: Without { passive: true }, the Compositor Thread waits on the main thread before scrolling in case preventDefault() is called.
When Not to Use
  • When not to use bubbling delegation: Events that do not bubble (mouseenter, mouseleave, focus, blur) require focusin/focusout or Capture-phase listeners, and bulk teardown is cleaner via AbortController { signal } options.

Connections & Logical Next Steps

What This UnlocksBaseline · Widely
Async Clipboard API and User Activation
Web APIs

Transient user activation is minted by trusted input events dispatching through the DOM.

What This UnlocksBaseline · Widely
The inert Attribute and Modal Focus Containment
DOM & Events

Inert subtrees suppress pointer and keyboard event dispatch during hit-testing before propagation.

What This UnlocksBaseline · Widely
Passive Event Listeners and Compositor Scrolling
DOM & Events

Passive flags are checked during hit-testing before dispatching wheel or touch propagation.

What This UnlocksBaseline · Widely
Pointer Events, touch-action, and Pointer Capture
DOM & Events

Pointer events follow standard capture/target/bubble propagation unless redirected by setPointerCapture().

What This UnlocksBaseline · Widely
Shadow DOM Encapsulation and Event Retargeting
DOM & Events

Shadow trees modify event propagation by retargeting event.target to the host at the ShadowRoot.

Under the HoodBaseline · Widely
Event Loop, Macrotasks, and Microtask Queue
JS Runtime

Each user interaction event is dispatched as a macrotask with a microtask checkpoint after every listener.

Under the HoodExperimental
Resumability vs Hydration
State & Architecture

Resumability relies on a single root event-delegation listener to intercept clicks before component JS loads.

Under the HoodBaseline · Widely
Roving Tabindex and Focus Order Mechanics
Security & Accessibility

A single keydown listener on the container intercepts Arrow keys via event bubbling.

Often Confused WithBaseline · Widely
AbortController and Cooperative Cancellation
JS Runtime

Passing an AbortSignal to addEventListener detaches groups of listeners without manual removeEventListener calls.

Seen in Architecture Autopsies

Mechanical Comparisons