Bubbling & capturing

The trip an event takes

On a web page, elements sit inside other elements. A button can sit inside a card. The card can sit inside a section. The elements around the button (its parent, the parent's parent, and so on) are called its ancestors.

When you click the button, the browser does not tell only the button. It makes one event object: an object that describes the click. Then it carries that object on a trip through the button's ancestors. The trip has three parts, called phases:

1. Capture: the event goes in, from the outside down to the button.
2. Target: the event reaches the button, the element you actually clicked.
3. Bubble: the event goes back out, from the button up to the outside.

A listener is a function you add with addEventListener. Any element on the trip can have listeners, so any of them can react to the click. This explains three everyday things:

• A card can hear a click on a button inside it.
• A menu can close when you click anywhere else on the page.
• One call to stopPropagation() can break code far away from that line.

You choose which half of the trip a listener joins. Pass { capture: true } as the third argument to addEventListener, and the listener runs on the way in. Leave the third argument out, and it runs at the target or on the way out.

1section.addEventListener("click", log, { capture: true });2card.addEventListener("click", log, { capture: true });3button.addEventListener("click", log, { capture: true });4 5button.addEventListener("click", log);6card.addEventListener("click", log);7section.addEventListener("click", log);

Lines 1 to 3 add capture listeners, so they run on the way in. Lines 5 to 7 leave the option out, so they run on the way out. Each line adds the same log function to one element.

1const card = document.querySelector("[data-box='card']");2 3card.addEventListener("click", () => console.log("capture"), { capture: true });4card.addEventListener("click", () => console.log("bubble"));5document.querySelector("[data-box='button']").click();

This example prints capture, then bubble. Line 3 passes { capture: true }, so its listener runs on the way in. Line 4 leaves the option out, so its listener runs on the way out. Line 5 clicks the button inside the card.

Older code writes true as the third argument instead. It means the same thing. The object form is easier to read, and it can hold other options too, such as once.

1const order = [];2const card = document.querySelector("[data-box='card']");3const button = document.querySelector("[data-box='button']");4 5card.addEventListener("click", () => order.push("card capture"), { capture: true });6button.addEventListener("click", () => order.push("button target"));7card.addEventListener("click", () => order.push("card bubble"));8button.click();9console.log(order.join(" > "));

This prints card capture > button target > card bubble. Line 5 runs first, because capture goes in from the outside. Line 6 runs next, on the button, the target. Line 7 runs last, when the event bubbles back out to the card. To guess the order, draw the trip first.

The full order for a click on the button is:

1. Capture listeners run from the outside in.
2. The button's own listeners run. Its capture listeners run before its normal ones in today's browsers. Older browsers did not always agree, so don't write code that needs this exact order.
3. Normal listeners run from the inside out. This only happens if the event's bubbles property is true.

The table lists the three phases. Read each row as: "in this phase, the event goes this way, eventPhase is this number, and this is how you listen."

The step-through below does not use a real page. It is a small plain-JavaScript copy of the trip, with a section, a card, a toolbar, a button, and an icon inside the button. Step through it to see the order. Then compare it with the real browser in the next section.

1const path = ["section", "card", "toolbar", "button", "icon"];2const listeners = ["capture", "bubble"];3 4for (const node of path.slice(0, -1)) {5  runListener(node, "capture");Run6}7 8runListener("button", "target capture");9runListener("button", "target bubble");10 11for (const node of ["toolbar", "card", "section"]) {12  runListener(node, "bubble");13}

Now try the browser's real events. The demo shows four boxes, one inside the other: a section, a card, a toolbar, and a button with a star in the middle. Each box has two bells:

• ↓ in rings when the box's capture listener runs, on the way in.
• ↑ out rings when the box's normal listener runs, on the way out.

Click the star and watch the bells ring in order. The numbers on the bells, and the row under the boxes, show the order.

Tap a bell to turn it off, or tap it again to give it a stop sign. A stop sign means that listener calls event.stopPropagation(). Then click the star again: every bell after the stop sign stays silent.

Game: guess the order

Now test yourself. Each level turns on a few bells. Tap them in the order you think they will ring, then click the star. The real click checks your guess. Get it right on the first try for three stars.

The demo and the game both add real listeners, like this:

1const boxes = document.querySelectorAll("[data-box]");2 3for (const box of boxes) {4  box.addEventListener("click", ringIn, { capture: true });5  box.addEventListener("click", ringOut);6}7 8function ringIn(event) {9  console.log(event.currentTarget.dataset.box, "in");10}11 12function ringOut(event) {13  console.log(event.currentTarget.dataset.box, "out");14}

target vs currentTarget

The event object has two properties that are easy to mix up:

• event.target is the element where the event started: the deepest element you clicked.
• event.currentTarget is the element whose listener is running right now.

In the demo, click the star. The star is a span inside the button. In the section's log line, target is still the span, but currentTarget is the section.

1const card = document.querySelector("[data-box='card']");2 3card.addEventListener("click", (event) => {4  console.log(event.target.dataset.box);5  console.log(event.currentTarget.dataset.box);6});7 8document.querySelector("[data-box='button']").click();

This prints button, then card. Line 8 clicks the button, so the button is the target. The listener belongs to the card, so the card is the currentTarget. As the event moves on, currentTarget changes to each new element. target stays the same.

The table compares three things you can read from the event. Read each row as: "this property tells you this, and in the star demo it is this."

1const button = document.querySelector("[data-box='button']");2 3button.addEventListener("click", (event) => {4  console.log(event.composedPath().slice(0, 3).map((node) => node.dataset.box || node.tagName).join(" > "));5});6 7button.click();

This prints button > toolbar > card. composedPath() returns an array of the elements the event passes through. It starts at the target and goes outward. Line 4 keeps the first three and prints their data-box names.

It also works with shadow DOM, a way for a component to hide its inner elements. There, walking up with parentElement can miss steps, but composedPath() still lists the whole trip.

Sometimes a listener needs to end the trip. For example, a dialog box may want to keep its own clicks away from a page listener that closes it. event.stopPropagation() does this: the event does not go on to any more elements.

It does not stop other listeners on the same element. They still run.

Three methods have similar names. The table shows what each one stops. Read each row as: "this method stops these things, and not the others."

The browser's built-in action is what it does on its own, such as following a link or sending a form. Only preventDefault() stops that.

1const button = document.querySelector("[data-box='button']");2const log = [];3 4button.addEventListener("click", (event) => {5  log.push("first");6  event.stopImmediatePropagation();7});8button.addEventListener("click", () => log.push("second"));9button.click();10console.log(log.join(" > "));

This prints only first. The button has two listeners. The first one calls stopImmediatePropagation() on line 6. So the second listener, on line 8, is skipped, and no ancestor hears the click. If line 6 called stopPropagation() instead, both button listeners would run and it would print first > second. The ancestors would still hear nothing.

Every event goes through the capture phase. But only events whose bubbles property is true go back out. Some common events don't bubble, and each has a partner that does:

• focus and blur don't bubble. focusin and focusout do.
• mouseenter and mouseleave don't bubble. mouseover and mouseout do.

1panel.addEventListener("focus", log, true);2panel.addEventListener("focus", log);3panel.addEventListener("focusin", log);4 5panel.addEventListener("mouseenter", log, true);6panel.addEventListener("mouseenter", log);7panel.addEventListener("mouseover", log);8 9function log(event) {10  console.log(event.type, event.bubbles);11}

1const card = document.querySelector("[data-box='card']");2const button = document.querySelector("[data-box='button']");3const log = [];4 5card.addEventListener("focus", () => log.push("focus capture"), true);6card.addEventListener("focus", () => log.push("focus bubble"));7card.addEventListener("focusin", () => log.push("focusin bubble"));8button.focus();9console.log(log.join(" > "));

This prints focus capture > focusin bubble. Line 8 puts the focus on the button inside the card.

• Line 5 is a capture listener, so it hears focus on the way in.
• Line 6 is a normal listener for focus. It never runs, because focus does not bubble.
• Line 7 listens for focusin, which bubbles, so it runs.

So when a form wrapper needs to know that focus went into one of its fields, listen for focusin and focusout.

1const card = document.querySelector("[data-box='card']");2const button = document.querySelector("[data-box='button']");3const log = [];4const record = (event) => log.push(event.type + " " + event.bubbles);5 6card.addEventListener("mouseenter", record, true);7card.addEventListener("mouseenter", record);8card.addEventListener("mouseover", record);9button.dispatchEvent(new MouseEvent("mouseenter", { bubbles: false }));10button.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));11console.log(log.join(" > "));

This prints mouseenter false > mouseover true. Each log shows the event's name and its bubbles value. Lines 9 and 10 send the two events to the button.

• Line 6 is a capture listener, so it hears mouseenter on the way in.
• Line 7 is a normal listener for mouseenter. It never runs, because mouseenter does not bubble.
• Line 8 listens for mouseover, which bubbles, so it runs.

Use mouseover when an ancestor should hear the pointer moving onto its inner elements. Use mouseenter when you want one event per element, with no bubbling.

Where you will use this

You will use the trip in real code. It lets one listener handle a whole area of the page. It is also why one part of a page can block another part by accident.

1const menu = document.querySelector(".menu");2const button = document.querySelector(".menu-button");3 4document.addEventListener("click", (event) => {5  const clickedInside = menu.contains(event.target) || button.contains(event.target);6  if (!clickedInside) menu.hidden = true;7});8 9button.addEventListener("click", (event) => {10  event.stopPropagation();11  menu.hidden = !menu.hidden;12});

• Lines 4 to 7 add a listener to the whole document. Clicks anywhere bubble up to it.
• Line 5 checks whether the click was inside the menu or its button. contains() returns true if the element is the same one or sits inside it.
• Line 6 hides the menu if the click was outside.
• Line 10 stops the menu button's own click, because a click on the button is not an outside click.

In a bigger app, you might skip the stop on line 10. Instead, the document listener can check the trip with composedPath().

1const log = [];2const card = document.querySelector("[data-box='card']");3const button = document.querySelector("[data-box='button']");4 5card.addEventListener("click", () => log.push("analytics"));6button.addEventListener("click", (event) => {7  event.stopPropagation();8  log.push("button");9});10button.click();11console.log(log.join(" > "));

This prints button, not button > analytics. Line 5 gives the card a listener that records clicks for analytics. But line 7 stops the event at the button, before it can bubble up to the card. So the analytics listener never records the click.

In a real app, a stop like this can quietly break analytics, keyboard shortcuts, or a menu that closes on outside clicks. When you can, let the event bubble and add a check in the ancestor's listener instead.

1document.body.innerHTML = '<button class="open-modal">Open</button><div class="modal" hidden>Details</div>';2const modal = document.querySelector(".modal");3const openButton = document.querySelector(".open-modal");4 5document.addEventListener("click", (event) => {6  if (!event.composedPath().includes(modal) && !event.composedPath().includes(openButton)) {7    modal.hidden = true;8  }9});10openButton.addEventListener("click", () => { modal.hidden = false; });11openButton.click();12document.body.click();13console.log(modal.hidden);

This prints true, which means the modal is hidden again. A modal is a box that opens on top of the page.

1. Line 11 clicks the Open button, and its listener on line 10 shows the modal.
2. That click also bubbles to the document. Line 6 finds the Open button in the trip, so the modal stays open.
3. Line 12 clicks the page body. That click bubbles to the document listener on line 5.
4. Line 6 checks the trip. Neither the modal nor the Open button is in it, so line 7 hides the modal.

This code never stops the trip, so other document listeners still hear every click. In a real app, also close the modal when the user presses Escape, and move the focus back to the Open button.

Common misconceptions

Try each question once before you read the explanations.

Key takeaways

• An event takes a trip in three phases: capture (in), target, then bubble (out).
• event.target is where the event started. event.currentTarget is the element whose listener is running.
• eventPhase is 1 for capture, 2 at the target, and 3 for bubble. composedPath() lists the whole trip.
• stopPropagation() stops later elements. stopImmediatePropagation() also skips this element's other listeners. preventDefault() stops the browser's built-in action.
• Some events don't bubble. When an ancestor must hear them, use the partners that do: focusin/focusout and mouseover/mouseout.

Up next: Event delegation. You will use bubbling on purpose, so one listener can handle many elements.