Event flow
Event flow describes the path an event takes through the page when something happens, such as a click on a button. The event does not just fire on the button; it travels from the top of the document down to the button and then back up again. Knowing this path explains why a click on a child can also trigger a listener on its parent, and how you can control which listener runs first.
The three phases
When you click an element, the browser dispatches the event in three phases:
- Capturing phase. The event starts at
window, thendocument, then<html>, and travels down through each ancestor toward the clicked element. - Target phase. The event arrives at the element that was actually clicked, called the target.
- Bubbling phase. The event travels back up the same path, from the target's parent all the way to
window.
Listeners added with addEventListener run in the bubbling phase by default. Passing { capture: true }, or simply true, as the third argument makes a listener run during capturing instead.
Watching the flow in action
<div id="outer">
<div id="inner">
<button id="btn">Click me</button>
</div>
</div>
<script>
const ids = ['outer', 'inner', 'btn'];
ids.forEach((id) => {
const el = document.getElementById(id);
el.addEventListener('click', (e) => {
console.log(`capture: ${id} (phase ${e.eventPhase})`);
}, { capture: true });
el.addEventListener('click', (e) => {
console.log(`bubble: ${id} (phase ${e.eventPhase})`);
});
});
</script>
<!-- Clicking the button logs:
capture: outer (phase 1)
capture: inner (phase 1)
capture: btn (phase 2)
bubble: btn (phase 2)
bubble: inner (phase 3)
bubble: outer (phase 3) -->
The eventPhase property reports the phase as a number: 1 for capturing, 2 for at target and 3 for bubbling. On the target itself both listeners fire in phase 2, in the order they were registered.
target versus currentTarget
Every listener receives the same event object, and two properties tell you where you are on the path:
| Property | Refers to |
|---|---|
event.target | The element where the event started, the deepest element clicked. It stays the same throughout. |
event.currentTarget | The element whose listener is running right now. It changes as the event travels. |
If the button contained an icon <span> and the user clicked the icon, target would be the span, not the button. Use event.target.closest('button') to find the nearest matching ancestor.
Controlling the flow
event.stopPropagation()stops the event from moving to further elements on the path, though other listeners on the current element still run.event.stopImmediatePropagation()also skips remaining listeners on the current element.event.preventDefault()is different: it cancels the browser's default action, such as following a link, but does not stop the event's travel.
Not every event bubbles. focus, blur, mouseenter and mouseleave do not, although focusin and focusout are bubbling alternatives. Capturing still reaches them, which is one practical use of capture listeners.
Mistake: stopping propagation too eagerly
Calling stopPropagation() to fix one problem often creates another. A common case is a dropdown that closes when you click anywhere on the document. If a component inside the page stops click propagation, the document listener never hears those clicks and the dropdown stays open. Analytics scripts and other libraries listening higher up break the same way. Before stopping propagation, check whether you can instead test event.target inside the parent listener and ignore clicks you do not care about.
Remember the path
Events travel down in the capture phase, hit the target, then bubble up. Listeners bubble by default, target is where the event began and currentTarget is where the listener lives. Use stopPropagation() sparingly. The next lesson builds on this to explain bubbling and capturing in more depth, including event delegation.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.