DOM Events

The 30-second version

Three bugs every front-end developer meets sooner or later: a click handler that runs twice, a dropdown that closes when you click inside it, and a table of 10,000 rows that gets slow because every row has its own listener. All three come from the same mechanism. Once you see it, they stop being mysteries.

First, the words. The page you see is a tree of objects called the DOMDOMThe Document Object Model: the browser's tree of objects that represents the page. Every button, input and div is a DOM node you can attach event listeners to.: <html> contains <body>, which contains your <ul>, which contains <li> rows, and so on (the trees topic covers trees in general). An eventEvent (DOM)A small object the browser creates when something happens — a click, a key press, a page finishing loading. It says what happened (type), where (target) and carries details like the mouse position or the key. is a small object the browser makes when something happens: a click, a key press, a field getting focus. A listenerEvent listener (handler)A function you register on an element with addEventListener. The browser calls it, passing the event object, every time that kind of event reaches the element. is a function you ask the browser to call when a certain event reaches a certain element.

button.addEventListener("click", (event) => {
  console.log("clicked!", event.target); // event.target = the element that was clicked
});

Most listeners you'll ever write run on the way up (the bubble phase). That one fact explains a lot:

The plan: §02–§04 teach the mechanism (listeners, phases, stopping and default actions), §05–§07 the everyday patterns (delegation, which events bubble, keyboard and pointer input), §08–§10 timing and React, §11 production concerns. Then pitfalls, a quiz and a cheat sheet.

Events, listeners and their options

The event object

Every Event listenerEvent listener (handler)A function you register on an element with addEventListener. The browser calls it, passing the event object, every time that kind of event reaches the element. receives one argument: the eventEvent (DOM)A small object the browser creates when something happens — a click, a key press, a page finishing loading. It says what happened (type), where (target) and carries details like the mouse position or the key.. Here are the fields you'll use most:

Plus details for each kind: clientX/clientY (pointer position) on mouse events, key on keyboard events, and so on. The difference between event.targetevent.targetThe element the event actually happened on — the deepest element under the pointer for a click, the focused field for a key press. It stays the same for the whole journey. and event.currentTargetevent.currentTargetThe element whose listener is running right now. It changes as the event travels, and it is null again once dispatch is over. becomes important in §05. For now, remember: target = where it happened, currentTarget = where you're listening.

Adding and removing

const button = document.querySelector("#buy");

function onBuy(event) {
  console.log("buy!", event.type); // "buy! click"
}

button.addEventListener("click", onBuy);    // start listening
button.removeEventListener("click", onBuy); // stop: same type, SAME function

The browser keeps, for each element, a list of (event type, function, capture flag) entries. The capture flag says whether the listener runs on the event's way down the page tree or on its way back up; §03 explains both, and for now "up" is the default. Two rules about that list cause many real bugs:

1. Adding the exact same function twice does nothing. The browser ignores the duplicate. But two arrow functions that look the same are two different functions, so both get added, and your handler runs twice. That is bug #1 from §01: a component that runs addEventListener("click", () => …) every time it sets itself up.
2. Removing needs the exact same function and capture flag. removeEventListener("click", () => …) removes nothing, because that arrow function is brand new. And if you added with { capture: true }, you must remove with { capture: true } too.

We checked both rules in headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would. (Chrome's engine, driven by a script with no visible window; we use it to measure every claim in this topic): the same function added twice ran 1 time, two identical-looking arrows ran 2 times, and a remove with the wrong capture flag left the listener in place. Try it yourself:

The options object

The third argument is an options object. Each option answers one question:

const controller = new AbortController();

button.addEventListener("click", onBuy, {
  once: true,                 // remove me automatically after the first call
  capture: false,             // run on the way down (true) or the way up (false, the default) — §03
  passive: true,              // "I promise not to call preventDefault()" (which cancels the browser's own action, §04) — §08
  signal: controller.signal,  // remove me when controller.abort() is called
});

controller.abort(); // ← removes every listener that was given this signal

onclick versus addEventListener

You'll also see button.onclick = fn and <button onclick="…"> in older code. That is a single slot: assigning it again replaces the previous function. addEventListener keeps a list, so a second listener doesn't overwrite the first. Use addEventListener in plain JavaScript. (React's onClick prop is a different thing entirely; see §10.)

Capture, target, bubble

Back to the sorting office from §01. The letter's route is decided before it starts moving: the browser takes the target element and lists every ancestor up to window. That list is the propagation path (you can see it yourself with event.composedPath()). Then the event walks that path in three phases. This journey is called PropagationPropagationThe journey an event takes through the page tree: down from the window to the target (capture phase), at the target, then back up (bubble phase). Listeners along the path run in that order..

Here is a real log from headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would.. Three nested elements, outer > middle > inner, each with one capture listener and one bubble listener. We clicked inner:

outer capture  (phase 1)
middle capture (phase 1)
inner capture  (phase 2)   ← at the target
inner bubble   (phase 2)   ← still at the target
middle bubble  (phase 3)
outer bubble   (phase 3)

With listeners on window, document and <body> too, the outer layers wrap around this: window capture, document capture, body capture, …, body bubble, document bubble, window bubble.

Now try it. The boxes below are real elements with real listeners. Switch listeners on and off, click the button, then click the <div>'s padding, and see which listeners run and in what order. (Ignore the stop controls for now: §04 explains them and uses them.)

Three things to notice while you play:

• Click the <div> padding instead of the button. Now the <div> is the target. Its capture listener (if on) runs in phase 2, not phase 1, and the button's listeners don't run at all: the button isn't on the path.
• Registration order only matters on one element. On the button, "listener 1" always runs before "listener 2" because it was added first. Between different elements, the phase decides.
• At the target, capture listeners run first. The target's capture listeners run before its non-capture ones, whatever order you added them in: we registered the bubble listener first and the capture one still ran first. This has been the rule in Chrome since version 89, after a change to the DOM standard; Firefox and Safari follow the same standard, but we only measured Chromium. Older browsers ran them in registration order, so old blog posts may tell you otherwise.

// Runs before ANY listener inside the page sees the click:
document.addEventListener("click", logClick, { capture: true });

// The old way to write the same thing: a bare `true` as the third argument.
document.addEventListener("click", logClick, true);

Stopping events and default actions

Three methods, three different jobs

We measured the first two on a button with two listeners and a parent <div> listener. The first button listener calls the method:

stopPropagation():          btn handler 1, btn handler 2      ← div never hears it
stopImmediatePropagation(): btn handler 1                     ← nothing else runs

You can reproduce this in the propagation lab in §03: pick "button · listener 1" in the drop-down, then flip the toggle at the top between the two methods.

Default actions

Many events come with something the browser does by itself once your listeners have run. preventDefault() cancels it, but only if the event is cancelable (most user-input events are; scroll and focus are not).

Try each one. The left switch decides whether its listener calls preventDefault():

Two details the lab shows that surprise people:

• The checkbox flips first, then flips back. Inside the click listener, checked already has the new value. If you call preventDefault(), the browser puts it back after the listeners finish. Our measured log: inside the listener checked=true; after the event checked=false.
• Pressing Enter in a form field clicks the submit button. We measured the order: click on the submit button first, then submit on the form, with event.submitter (the button that sent the form) pointing at that button. So handle submit on the form, not click on the button, or you'll miss Enter.

Why stopPropagation() is usually the wrong fix

Here is bug #2 from §01. A dropdown closes when you click outside it, using one listener on document. But a click inside the menu bubbles up to document too, so the menu closes when you click its own search box.

The tempting patch is stopPropagation() inside the menu. It works, but it hides those clicks from every listener further up: analytics, other "click outside" handlers, a parent component's logic. The real fix is to ask the right question in the document listener: "was this click inside the menu?" Compare the three versions:

document.addEventListener("click", (e) => {
  if (!toggleButton.contains(e.target)) close(); // any other click closes
});

// menu = the wrapper around BOTH the toggle button and the panel.
// If it were only the panel, the click that OPENS the menu would also
// reach this listener and close it again straight away.
const menu = document.querySelector("#filter-menu");

document.addEventListener("click", (event) => {
  if (!menu.contains(event.target)) closeMenu(); // ← only clicks outside the menu
});

Event delegation: one listener for many children

That's Event delegationEvent delegationPutting one event listener on a parent and using event.target to see which child was hit, instead of one listener per child.. Here's the code for a to-do list where each row has a ★ and a ✕ button:

<ul id="todos">
  <li data-id="1"><span>Write the report</span>
    <button data-action="star">★</button>
    <button data-action="delete">✕</button>
  </li>
  <!-- …and 9,999 more rows -->
</ul>

const list = document.querySelector("#todos");

list.addEventListener("click", (event) => {             // ← the only listener
  const button = event.target.closest("button[data-action]");
  if (!button || !list.contains(button)) return;        // not on an action button: ignore
                                                        // (contains: closest() could climb past the list)

  const id = button.closest("li").dataset.id;           // which row?
  if (button.dataset.action === "delete") deleteTodo(id);
  if (button.dataset.action === "star") toggleStar(id);
});

Why closest() and not just event.target? Because target is the deepest element that was hit. If the button contained an icon <svg>, a click on the icon makes target the <svg> (or even a <path> inside it), not the button. closest() climbs from wherever the click landed to the element you care about. And currentTarget is always the <ul>, the element the listener is on. Click around and watch all three:

Notice that rows you add later work straight away. With per-row listeners, every new row needs its own addEventListener, and every deleted row should have its listener removed. With delegation, the list's single listener covers rows that don't exist yet.

What it saves, measured

We built a 10,000-row list in headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would. and attached click handlers three ways:

• One arrow function per row is the expensive one: each arrow is a new function object plus a ClosureClosureA function that remembers the variables around where it was created, even after that outer function has returned. Both Go and JS have them. holding that row's variables, about 70 bytes of JS heap per row here, and it took ~8 ms to attach.
• One shared function on every row costs almost no JS memory, but still makes 10,000 entries in the browser's internal listener lists, and still took ~3.5 ms.
• One delegated listener costs nothing measurable either way.

When delegation doesn't fit

• Events that don't bubble (focus, mouseenter, load on images…) never reach the parent. Use their bubbling twins where they exist (§06).
• High-frequency events like pointermove on a whole page: a delegated listener runs for every move anywhere inside, then filters. That's fine when the filtering is cheap; profile it if it isn't.
• Something below calls stopPropagation(): the event never reaches your listener. Another reason to avoid it (§04).

Not every event bubbles

Every event object has a bubbles property. When it's false, the event still goes through the capture phase and the target, but skips the trip back up. So a normal (bubble) listener on a parent never runs. Here are the ones that catch people out:

Move the pointer over the card and its child, and click between the two fields. Every listener here is on the outer element:

We measured one path on a bare test page (enter the card, move into the child, back out to the card, then leave): 3 mouseover (plus 3 mouseout) but only 1 mouseenter (plus 1 mouseleave). Here is the full log, listeners on the card only:

mouseover:card  mouseenter:card                ← pointer enters the card
mouseout:card   mouseover:child                ← crosses into the child
mouseout:child  mouseover:card                 ← back out to the card
mouseout:card   mouseleave:card                ← leaves

The mouseover with target=child bubbled up from the child, and moving between card and child produced a mouseout and a mouseover each time, although the pointer never left the card. The widget's counters run higher if your path crosses the child more often. For the form: a listener for focus on the form never ran, while focusin ran once per field.

Shadow DOM: the event pretends to come from the host

Some elements carry a private sub-tree, the Shadow DOMShadow DOMA hidden sub-tree attached to an element (used by web components and some built-in controls like <video>). Its inside is private: outside code sees only the host element.. Web components (your own custom HTML tags, like <date-picker>, defined in JavaScript) use it, and so do some built-in controls (the play button inside <video> is one). Its insides are hidden from the rest of the page, and events respect that.

When a click happens inside a shadow tree and travels out into the page, the browser retargets it: outside the shadow tree, event.target becomes the host element, so page code never sees the private insides. Measured:

inside shadow root: target=#inside
document:           target=div#host; composedPath()[0]=#inside

Whether an event may leave a shadow tree at all is the composedcomposed (event flag)Whether an event may travel out of a shadow DOM into the main page. Built-in UI events like click are composed; custom events are not unless you pass composed: true. flag. Built-in UI events like click, keydown and input are composed. Events you create yourself are not, unless you say so:

// Inside a web component's shadow tree:
button.dispatchEvent(new CustomEvent("ping", { bubbles: true }));
// → heard inside the shadow root only

button.dispatchEvent(new CustomEvent("ping", { bubbles: true, composed: true }));
// → heard inside the shadow root AND on document (measured)

Pointer, keyboard and form events in practice

Open the inspector and try things while you read. Everything in it is a real listener logging real events:

Pointer events: one API for mouse, touch and pen

Phones send touch events, laptops send mouse events, tablets send pen events. Pointer eventsPointer eventsOne family of events (pointerdown, pointermove, pointerup, …) for mouse, touch and pen alike. event.pointerType says which one it was, so one handler covers all three. (pointerdown, pointermove, pointerup, pointercancel) cover all three, and event.pointerType tells you which it was. The browser still sends the older mouse and touch events too, for old code. Measured order for one click and one tap:

mouse click: pointerdown(mouse) mousedown  pointerup(mouse) mouseup  click
finger tap:  pointerdown(touch) touchstart pointerup(touch) touchend  mouseover mousedown mouseup click

So a tap produces a click too. That's why handling click alone works for buttons on every device, and why listening to both touchstart and mousedown for the same action runs your code twice on a phone. If you need press/drag/release, use pointer events and only pointer events.

handle.addEventListener("pointerdown", (event) => {
  handle.setPointerCapture(event.pointerId); // ← keep getting moves even if the pointer leaves the handle
  startDrag(event.clientX, event.clientY);
});
handle.addEventListener("pointermove", (event) => {
  if (!handle.hasPointerCapture(event.pointerId)) return; // just hovering, not dragging
  moveDrag(event.clientX, event.clientY);
});
handle.addEventListener("pointerup", endDrag);
handle.addEventListener("pointercancel", endDrag); // the browser took over (e.g. started scrolling)

Keyboard: key versus code

We measured the US-layout values in Chromium: Shift+KeyA gave key="A", code="KeyA", and Shift+Digit1 gave key="!" but code="Digit1". (The AZERTY column follows from where that layout puts its letters; we didn't measure it.) Rule: use key for shortcuts named by letter ("press ? for help", Escape, Enter) and code for position-based controls (WASD in a game). Avoid the old keyCode: it's deprecated and its numbers vary by browser and layout.

IME composition: when one character takes many keys

People typing Japanese, Chinese, Korean and other languages use an IMEIME (input method editor)The operating-system tool people use to type languages like Japanese, Chinese or Korean: you type several keys, pick a suggestion, and only then is the final text committed to the field.: they type several keys, pick a suggestion, then commit. While they're choosing, the field shows a draft, and the browser fires composition events. Measured, typing に → にほ → 日本:

compositionstart  data=""
compositionupdate data="に"    input data="に"
compositionupdate data="にほ"  input data="にほ"
compositionupdate data="日本"  input data="日本"
compositionend    data="日本"

The input events during composition carry draft text. If you run a search or validation on every input, you'll search for half-typed words. And if you submit on Enter in keydown, you'll submit while the user is just confirming their choice in the IME. Check event.isComposing first:

input.addEventListener("keydown", (event) => {
  if (event.isComposing) return;   // ← the IME is using this Enter, not us
  if (event.key === "Enter") send();
});

Safari has a reported quirk here: the Enter that commits a composition can arrive after compositionend with isComposing already false (we couldn't test it; only Chromium is installed here). If you support Safari IME users, also ignore an Enter that comes right after a compositionend, or test with a real Japanese keyboard.

input vs change, and form submit

• input fires on every edit: each keystroke, paste, cut, or IME update. Use it for live feedback (character counters, live search with a debounce, §09).
• change fires when the value is committed: for a text field, when it loses focus or you press Enter (measured: change after Enter); for a checkbox, select or radio, right away.
• submit fires on the <form>, whether the user clicked the button or pressed Enter in a field. Handle it there, call event.preventDefault() if you send it with fetch(), and read the values with new FormData(form).

form.addEventListener("submit", async (event) => {
  event.preventDefault();                     // ← stay on this page
  const data = new FormData(form);            // every named field
  const res = await fetch("/api/search", { method: "POST", body: data });
  if (!res.ok) showError(`Search failed: ${res.status}`); // fetch doesn't throw on 404/500
});

When handlers run: tasks, frames and passive listeners

Listeners are tasks on the main thread

Everything in this topic runs on one thread, the Main threadMain threadThe single browser thread that runs your JavaScript and also does style, layout and most painting. While it's busy with a long task, the page can't respond to clicks or update., which also lays out and paints the page. When you click, the browser puts a task in a queue; the Event loopEvent loopThe loop inside every JS runtime that repeatedly picks the next piece of waiting work (a callback) and runs it to completion on the single main thread. picks it up and dispatches the event, calling your listeners one after another. How the loop picks tasks and when microtasksMicrotaskA tiny job — like a promise's .then callback or the code after an await — that JS runs right after the current code finishes, before timers, clicks or I/O. run is covered in Async / Await §07. Two consequences matter here:

• A slow listener freezes the page. While it runs, nothing repaints and no other click is handled. Any main-thread job over 50 ms is called a Long taskLong taskAny single piece of main-thread work that runs longer than 50 ms. While it runs, the page can't draw new frames or respond to clicks.. The time from a click to the next painted frame is what Google's INPINP (Interaction to Next Paint)A Core Web Vital: roughly, the slowest delay on a page between a user's tap, click or key press and the next frame that shows the result. Under 200 ms counts as good. metric measures (more in Web Performance).
• Microtasks run between listeners, but only for real input. Microtasks run whenever the call stack is empty. During a real click, the stack is empty between one listener and the next. During el.click() from your script, it isn't: your script is still on the stack.

Step through it:

1btn.addEventListener("click", () => {
2  Promise.resolve().then(() => log("micro 1"));
3  log("listener 1");
4});
5btn.addEventListener("click", () => {
6  Promise.resolve().then(() => log("micro 2"));
7  log("listener 2");
8});
9 
10// Case A: a person clicks the button.
11// Case B: a script does it:
12btn.click();
13log("after click()");

We logged both orders in headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would.: real mouse click → listener 1, microtask 1, listener 2, microtask 2; btn.click() → listener 1, listener 2, after click(), microtask 1, microtask 2.

requestAnimationFrame: the right moment for visual changes

The screen is redrawn in frames, usually 60 per second (90 or 120 on many newer phones and laptops), so at 60 Hz each frame has about 16.7 ms: the Frame budgetFrame budgetAt 60 frames per second each frame gets about 16.7 ms for JavaScript, style, layout, paint and compositing. Go over it and animations stutter (“jank”).. (How a frame is built is in How Browsers Render.) requestAnimationFramerequestAnimationFrameA browser function that runs your callback just before the next frame is drawn — the right moment to update anything visual. asks the browser to call you just before the next frame is drawn. We counted 61 callbacks in one second in headless Chromium, one per frame.

let latestX = 0;
let scheduled = false;

window.addEventListener("pointermove", (event) => {
  latestX = event.clientX;          // just remember the newest value (cheap)
  if (scheduled) return;            // a frame is already booked
  scheduled = true;
  requestAnimationFrame(() => {     // ← once per frame, right before painting
    scheduled = false;
    dot.style.transform = `translateX(${latestX}px)`;
  });
});

Why not update the DOM directly in the listener? Some input events can arrive more often than frames are drawn, and every DOM write in between is wasted work nobody sees. Writing in rAF does at most one update per frame, always with the newest value. Chromium already lines up continuous events like pointermove and wheel with frames on most devices, so this pattern costs nothing and protects you on the ones where it doesn't. (event.getCoalescedEvents() gives you the in-between pointer positions if you're drawing a smooth line.)

Passive listeners and smooth scrolling

When you swipe or spin the wheel, the browser wants to scroll immediately, ideally on a separate thread, the compositorCompositor threadA browser thread separate from the main thread. It assembles the layers into each frame and can move or fade a layer on its own, even while your JavaScript is busy. (How Browsers Render has the details). But if a touchstart, touchmove or wheel listener might call preventDefault() to cancel the scroll, the browser has to wait for your JavaScript first. If the main thread is busy, scrolling stutters.

A passive listenerPassive listenerA listener registered with { passive: true }: a promise that it will never call preventDefault(). The browser can then start scrolling straight away instead of waiting for your JavaScript. is your promise that you won't cancel:

window.addEventListener("touchmove", trackSwipe, { passive: true }); // the browser scrolls without waiting

If you break the promise, the call is ignored and Chromium logs a console error. Both measured:

preventDefault() in a { passive: true } listener → defaultPrevented: false
[error] Unable to preventDefault inside passive event listener invocation.

Browsers went one step further: wheel, touchstart and touchmove listeners on window, document or <body> are passive by default in Chromium and Firefox (Safari does this at least for the touch events; we only measured Chromium), because so many sites added them without needing to cancel. We added a plain document.addEventListener("wheel", e => e.preventDefault()) and spun the wheel: cancelable=false, the page scrolled 300 px anyway, and Chromium printed "Unable to preventDefault inside passive event listener due to target being treated as passive." If you really need to block scrolling (a map, a custom carousel), attach the listener to that element with { passive: false }.

Debounce and throttle

Some events arrive in floods: typing fires input per keystroke, dragging fires dozens of pointermove per second, resizing a window fires resize continuously. Often you don't need to react to every one.

Move your pointer over the pad below, stop for a moment, then move again. Each tick is one call. Try the three window sizes:

What you should see: raw and rAF lanes look almost the same. That's because Chromium already delivers pointermove at most about once per frame (§08). The Simulate button is different: it calls the handler every 12 ms, faster than the screen refreshes, so there the rAF lane is visibly sparser than raw (we saw about 100 raw ticks vs 63 rAF ticks). That gap is rAF doing its job: extra calls inside one frame are merged. Throttle ticks at a steady rhythm while you move. Debounce stays silent while you move and ticks once, a moment after you stop.

The code

function debounce(fn, ms) {
  let timer;                                  // shared by every call below
  return (...args) => {
    clearTimeout(timer);                      // ← cancel the previous plan
    timer = setTimeout(() => fn(...args), ms);
  };
}

const search = debounce((q) => fetchResults(q), 300);
input.addEventListener("input", (e) => search(e.target.value));

We ran both in Node 22 with 100 calls, one every 10 ms (a one-second burst), and a 300 ms window:

debounce: call 100 @ 1308 ms                   ← 1 run, 300 ms after the burst ended
throttle: 1 @ 11, 30 @ 312, 60 @ 612, 90 @ 913, 100 @ 1214   ← every 300 ms, plus the last one

Throttle's last run (call 100) is the trailing call: without it, the final position of a drag or scroll would be lost.

Which one when?

React's event system

You've written <button onClick={save}> many times. Here's what actually happens in ReactReactA JavaScript library for building user interfaces from components: you describe what the UI should look like for the current data, and React updates the DOM to match. 17 and later (we checked React 19.3):

1. When you call createRoot(container), React adds its own listeners to container: both a capture and a bubble listener for almost every event type. We counted about 140 listeners on the root in React 19.3 (the exact number varies a little between builds).
2. Your button gets no listener of its own for onClick.
3. When a real click bubbles up to the root, React looks at event.target, finds the components on the way up, and calls their onClick props in order. That's Event delegationEvent delegationPutting one event listener on a parent and using event.target to see which child was hit, instead of one listener per child. (§05), done for you.

Your handler gets a Synthetic eventSynthetic event (React)The wrapper object React passes to onClick and friends. It looks like the browser's event (target, preventDefault, stopPropagation) and keeps the real one in e.nativeEvent.: a wrapper with the familiar fields (target, currentTarget, preventDefault(), stopPropagation()) and the real browser event in e.nativeEvent. Click the button below, then try the two checkboxes:

Here's the measured order, with nothing stopped:

1. native · document (capture)
2. React · <div onClickCapture>        ← React's capture listener on the root
3. native · <button> addEventListener   ← the button really has this listener
4. React · <button onClick>             ← React's bubble listener on the root
5. React · <div onClick>
6. native · document (bubble)

Each line follows from the phases in §03 once you know React's listeners sit on the root:

• onClickCapture runs during the capture phase, when the event passes the root on its way down (step 2), so before the button's own listener.
• A native listener on the button runs before the button's React onClick (step 3 before 4): the event reaches the button before it bubbles up to the root.
• React's e.stopPropagation() stops both trees. React stops its own walk and calls the native stopPropagation(), so document listeners (step 6) don't run. Measured: lines 5 and 6 disappeared.
• A native stopPropagation() on the button hides the click from React completely. The event never reaches the root, so no React onClick above that point runs (measured: the log stops at line 3). This is how a third-party widget can "eat" clicks in your React app.

Native listeners in React components

Sometimes you need a real listener: on window (resize, keyboard shortcuts), on document (click outside), or with options React doesn't expose (passive: false). Add it in an effect and remove it in the cleanup:

import { useEffect } from "react";

function useKeyboardShortcut(key, onPress) {
  useEffect(() => {
    const controller = new AbortController();
    window.addEventListener("keydown", (event) => {
      if (event.key === key && !event.isComposing) onPress(event);
    }, { signal: controller.signal });
    return () => controller.abort();   // ← React calls this when the component goes away
  }, [key, onPress]); // wrap onPress in useCallback, or this re-subscribes on every render
}

In development, React's StrictMode sets every effect up, cleans it up, and sets it up again. If your cleanup forgets to remove the listener, you'll see the handler run twice: bug #1 from §01 again. Why React re-renders and what StrictMode does are covered in How React Works.

Production: leaks, custom events, postMessage, accessibility

1. Listener leaks keep whole components alive

A listener on a long-lived object (window, document, a global store) holds on to its function, and the function's ClosureClosureA function that remembers the variables around where it was created, even after that outer function has returned. Both Go and JS have them. holds on to whatever it uses, often the component's own DOM element. Remove the element from the page and forget the listener, and the garbage collectorGarbage collector (GC)Part of the language runtime that automatically frees memory nobody can reach anymore. Anything still referenced — like a stuck goroutine — is never freed. can't free any of it: the element is still reachable from window. That's a Memory leakMemory leakMemory that your program no longer needs but can't free, because something still holds a reference to it. In garbage-collected languages, a forgotten listener or map entry is the usual culprit., the classic one in single-page appsSingle-page app (SPA)A web app that loads one HTML page and then changes the view with JavaScript as you navigate, instead of loading a new page from the server each time., where the page itself is never reloaded to wipe the slate clean. The GC topic explains reachability in depth.

We measured it: 20 "page visits", each creating 50 cards that add a resize listener on window and then removing the cards from the page.

// Leaky: nothing ever removes the listener
function mountCard(card) {
  window.addEventListener("resize", () => {
    card.style.width = innerWidth / 3 + "px"; // ← keeps `card` alive
  });
}

for (const card of cards) mountCard(card);
// "leave the page":
app.replaceChildren(); // cards gone from the page,
                       // still reachable from window

// Fixed: one controller per page visit
function mountCard(card, signal) {
  window.addEventListener("resize", () => {
    card.style.width = innerWidth / 3 + "px";
  }, { signal });                          // ← removable
}

const controller = new AbortController();
for (const card of cards) mountCard(card, controller.signal);
// "leave the page":
app.replaceChildren();
controller.abort(); // ← removes all 50 listeners

Measured on this machine (headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would. 153) with Memory.getDOMCounters, a DOM-node counter that Chrome exposes to test scripts through its DevTools protocol. The 5 nodes left in the fixed version are the test page's own. Every removed card, with its heading, paragraph and button, stayed in memory. In DevTools, a heap snapshot filtered for "Detached" shows exactly these: elements no longer in the page but still reachable.

2. Custom events: components that talk without importing each other

Any element can fire events you invent, using CustomEventCustomEventAn event you create and fire yourself — new CustomEvent("cart:add", { detail, bubbles: true }) — so parts of a page can announce things without importing each other.. A product card can announce "added to cart" and the header badge can listen on document, without either importing the other. That's the observer pattern (Behavioral patterns) built into the DOM.

// The card announces:
const ok = card.dispatchEvent(new CustomEvent("cart:add", {
  detail: { sku: 42, qty: 1 }, // ← your data goes in `detail`
  bubbles: true,               // default is false: only the card itself would hear it
  cancelable: true,            // let listeners veto it with preventDefault()
}));
if (!ok) showMessage("Can't add that right now"); // a listener called preventDefault()

// The header listens, anywhere above:
document.addEventListener("cart:add", (event) => {
  badge.textContent = Number(badge.textContent) + event.detail.qty;
});

Things we measured that you need to know:

• bubbles defaults to false for events you make (the parent heard nothing until we passed bubbles: true). Built-in clicks bubble; your events don't unless you ask.
• dispatchEvent is synchronous. All listeners run before dispatchEvent returns, inside your code. Measured order: before dispatch → child handler → after dispatch. It's a function call through the DOM, not a message queue.
• It returns false if a listener called preventDefault() on a cancelable event. That's your veto mechanism.
• An exception in one listener doesn't stop the others. We threw an error in listener 1: listener 2 still ran, click() returned normally, and the error went to window's error event. Good for robustness, but errors in listeners never reach the code that dispatched the event, so make sure they reach your error reporting.

3. Cross-frame messages: always check the origin

A page and an iframeiframeAn HTML element (<iframe src=…>) that shows another web page inside a rectangle of the current page. The framed page keeps its own origin, so the outer page can't read inside it if it comes from elsewhere. from a different originOrigin (web)The scheme + host + port of a web page, e.g. https://chat.example.com. Browsers send it in the Origin header on cross-origin requests, POSTs and WebSocket handshakes, so the server can tell which website the request came from. can't touch each other's DOM (CORS & CSRF explains why). They talk with postMessagepostMessageThe browser API for sending data between windows that may come from different origins — a page and an iframe, or a popup. The receiver gets a message event saying which origin sent it. instead, and the receiver gets a message event. Any window that can get a reference to yours (an iframe you embed, a popup, the page that opened you) can send you messages. So the listener must check who sent each one.

We embedded two iframes, a real widget and an "evil" one. Both sent a "resize" message; this is what the parent's listener received:

message from https://widget.test: {"type":"resize","height":320}   source is widget frame: true
message from https://evil.test:   {"type":"resize","height":99999} source is widget frame: false

// Receiving: check the sender before trusting anything
window.addEventListener("message", (event) => {
  if (event.origin !== "https://widget.example.com") return;   // ← who sent it
  if (event.source !== widgetFrame.contentWindow) return;      // ← and from which frame
  if (event.data?.type === "resize") widgetFrame.style.height = `${Number(event.data.height)}px`;
});

// Sending: name the receiver's origin, never "*" for anything private
widgetFrame.contentWindow.postMessage({ type: "theme", value: "dark" }, "https://widget.example.com");

Why the sender names an origin

The second argument of postMessage protects your data. A frame's address can change after you embedded it: a compromised ad, an open redirect, or the frame's own bug can send it to another site, and your widgetFrame.contentWindow reference now points at that site. If you send a secret with "*", whoever is in the frame gets it.

We tested exactly that: the parent sends a token to a frame that started on widget.test, then the frame navigates itself to evil.test, and the parent sends again.

const frame = document.querySelector("#widget").contentWindow;

frame.postMessage("token=abc123", "https://widget.test"); // ← delivered only if the frame IS widget.test
frame.postMessage("token=abc123", "*");                   // ← delivered to whoever is in the frame now

frame on widget.test, target "https://widget.test" → widget got: token=abc123
frame on evil.test,   target "https://widget.test" → not delivered; console:
  Failed to execute 'postMessage' on 'DOMWindow': The target origin provided
  ('https://widget.test') does not match the recipient window's origin ('https://evil.test').
frame on evil.test,   target "*"                   → EVIL got: token=abc123

So: check event.origin when you receive, and name the exact origin when you send. Message data that ends up in innerHTML is a classic DOM-based XSSDOM-based XSSXSS that happens entirely in the browser: front-end JavaScript reads attacker-controlled data (location.hash, a postMessage) and writes it into the page with an unsafe API like innerHTML. The server may never see the payload. hole, so treat event.data like any other user input.

4. Accessibility: every click needs a keyboard path

Many people never use a mouse: keyboard users, Screen readerScreen readerSoftware (VoiceOver, NVDA, JAWS, TalkBack) that reads the page aloud and lets blind and low-vision users navigate it by headings, links, landmarks and form controls. users, switch-device users. A <div> with a click listener can't be reached with Tab and doesn't react to Enter or Space. A <button> does all of that for free, and it fires click for Enter and Space too, so one click listener covers everyone.

Both snippets below use inline onclick only to stay short; in real code attach the listener with addEventListener as in §02.

<!-- ✗ mouse-only: no focus, no Enter/Space, a screen reader says "group" or nothing -->
<div class="btn" onclick="save()">Save</div>

<!-- ✓ focusable, Enter and Space fire click, announced as "Save, button" -->
<button type="button" onclick="save()">Save</button>

Keep that parity everywhere: hover menus also open on focus, drag-and-drop has a keyboard alternative, and custom keyboard shortcuts skip key presses while the user is typing in a field. The Accessibility topic covers focus management and ARIA properly.

Pitfalls gallery

Eight bugs that show up in real code reviews, each with the fix. Every "measured" note comes from headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would. 153.

label.addEventListener("click", () => {
  toggleSetting(); // runs twice: undone again!
});

// listen for the state change instead:
checkbox.addEventListener("change", () => {
  toggleSetting(checkbox.checked); // once per real change
});

function setup() {
  button.addEventListener("click", () => save());
}
setup(); setup(); // two listeners → save() twice

let controller;
function setup() {
  controller?.abort();                // remove the old ones first
  controller = new AbortController();
  button.addEventListener("click", () => save(), { signal: controller.signal });
}

el.addEventListener("scroll", this.onScroll.bind(this), true);
// later:
el.removeEventListener("scroll", this.onScroll.bind(this)); // new function, wrong flag

this.onScroll = this.onScroll.bind(this); // bind ONCE, keep it
el.addEventListener("scroll", this.onScroll, true);
el.removeEventListener("scroll", this.onScroll, true);

form.addEventListener("submit", async (e) => {
  const ok = await validate();   // the listener returns here…
  if (!ok) e.preventDefault();   // …so this is too late: the form already submitted
});

form.addEventListener("submit", async (e) => {
  e.preventDefault();            // decide synchronously, first
  if (await validate()) await send(new FormData(form));
});

list.addEventListener("click", (e) => {
  setTimeout(() => e.currentTarget.classList.add("seen"), 100);
  // TypeError: Cannot read properties of null (reading 'classList')
});

list.addEventListener("click", (e) => {
  const el = e.currentTarget;            // copy it now
  setTimeout(() => el.classList.add("seen"), 100);
});

button.addEventListener("click", function () { this.disabled = true; }); // this = button
button.addEventListener("click", () => { this.disabled = true; });       // this = outer this (often undefined)
button.addEventListener("click", (e) => { e.currentTarget.disabled = true; }); // ✓ clear and safe

input.addEventListener("input", debounce((e) => renderResults(filter(e.target.value)), 200));
window.addEventListener("scroll", onScroll, { passive: true });

Check yourself: predict what happens

Commit to an answer before you click. Every answer was checked in headless ChromiumHeadless ChromiumChrome's engine run by a script with no visible window. Test tools like Playwright use it to click, type and measure exactly as a real browser would., and each explanation points to the section to re-read.

card.addEventListener("click", () => log("card bubble"));
btn.addEventListener("click",  () => log("btn"));
card.addEventListener("click", () => log("card capture"), { capture: true });

Cheat sheet