Event Capturing

The capturing phase is the first phase of event propagation, where the event travels from the window down to the target element.

How Capturing Works

<div id="a">
  <div id="b">
    <div id="c">Click me</div>
  </div>
</div>

<script>
// Capturing listeners (third arg = true)
document.getElementById('a').addEventListener('click', () => {
  console.log('A capturing');
}, true);

document.getElementById('b').addEventListener('click', () => {
  console.log('B capturing');
}, true);

// Bubble listener (third arg = false)
document.getElementById('c').addEventListener('click', () => {
  console.log('C'); // Target phase
});

// Bubbling listeners
document.getElementById('a').addEventListener('click', () => {
  console.log('A bubbling');
});

document.getElementById('b').addEventListener('click', () => {
  console.log('B bubbling');
});
</script>

Output:

A capturing
B capturing
C
B bubbling
A bubbling

Visual Flow

Window (capturing starts)
  ↓
  Document
    ↓
    HTML
      ↓
      Body
        ↓
        Div A (capturing)
          ↓
          Div B (capturing)
            ↓
            Div C (target)
              ↑
            Div B (bubbling)
          ↑
        Div A (bubbling)
      ↑
    Body
  ↑
Document
Window

The addEventListener method accepts options to control its behavior.

Third Argument (Legacy)

// Bubble phase (default)
element.addEventListener('click', handler, false);
element.addEventListener('click', handler); // Same as above

// Capture phase
element.addEventListener('click', handler, true);

Options Object (Modern)

element.addEventListener('click', handler, {
  capture: true,    // Listen in capturing phase
  once: true,       // Remove after first call
  passive: true,    // Never calls preventDefault()
  signal: controller.signal // AbortController signal
});

Practical Options Examples

// Once - auto-remove after first trigger
element.addEventListener('click', () => {
  console.log('Clicked once!');
}, { once: true });

// Passive - for scroll performance (can't prevent default)
document.addEventListener('touchmove', (e) => {
  console.log('Scrolling...');
  // e.preventDefault() would log warning
}, { passive: true });

// Signal - abort controller integration
const controller = new AbortController();
element.addEventListener('click', handler, {
  signal: controller.signal
});
// Later: controller.abort(); // Removes listener

Checking Listener Options

// Not directly possible to check existing listener options
// But you can manage listeners manually
function addManagedListener(element, type, handler, options) {
  element.addEventListener(type, handler, options);
  
  return () => {
    element.removeEventListener(type, handler, options);
  };
}

// Usage
const removeListener = addManagedListener(
  element, 'click', handler, { capture: true }
);
// Later: removeListener();

Capturing is less commonly used than bubbling, but has specific use cases.

Use Cases for Capturing

1. Intercepting Events Early

// Global click tracking - capture ALL clicks
document.addEventListener('click', (e) => {
  trackClick(e.target, e.clientX, e.clientY);
}, true); // Capture phase ensures we see it first

2. Preventing Event Handling

// Disable all clicks in a section during loading
document.getElementById('content').addEventListener('click', (e) => {
  e.stopPropagation();
  e.preventDefault();
}, true); // Capture phase blocks before handlers run

3. Event Delegation with Capture

// Handle clicks on dynamic content
document.addEventListener('click', (e) => {
  const button = e.target.closest('.dynamic-button');
  if (button) {
    handleButtonClick(button);
  }
}, true); // Capture ensures we catch it early

4. Debugging

// Log all events for debugging
document.addEventListener('click', (e) => {
  console.log('Click captured at:', e.target);
}, true);

When NOT to Use Capturing

• Most UI interactions (use bubbling)
• When you want child handlers to run first
• When you need stopPropagation to work from child to parent

Decision Guide

Need to intercept before child handlers? → Capturing
Need to track all events globally? → Capturing
Need default child behavior? → Bubbling