Key Takeaways
- Event bubbling in JavaScript refers to the order in which event handlers are called when one element is nested inside a second element, and both elements have registered a listener for the same event. Understanding event bubbling, along with event capturing and event propagation, is essential for working with events in JavaScript.
- Event propagation is a term for both event bubbling and event capturing. It refers to the process of calling all the listeners for the given event type, attached to the nodes on the branch of the DOM tree. The propagation is bidirectional and can be divided into three phases: the capture phase, the target phase, and the bubble phase.
- Event propagation can be stopped in any listener by invoking the stopPropagation method of the event object. This halts the propagation, meaning that all the listeners registered on the nodes on the propagation path that follow the current target will not be called.
- Some events are associated with a default action that the browser executes at the end of the propagation. This default action can be avoided with event cancellation, by calling the preventDefault method in a listener.
Event bubbling is a term you might have come across on your JavaScript travels. It relates to the order in which event handlers are called when one element is nested inside a second element, and both elements have registered a listener for the same event (a click, for example).
But event bubbling is only one piece of the puzzle. It is often mentioned in conjunction with event capturing and event propagation. And a firm understanding of all three concepts is essential for working with events in JavaScript — for example if you wish to implement the event delegation pattern.
In this post I will explain each of these terms and demonstrate how they fit together. I will also show you how a basic understanding of JavaScript event flow can give you fine-grained control over your application. Please note that this is not a primer on events, thus a familiarity with the topic is assumed. If you’d like to learn more about events in general, why not check out our book: JavaScript: Novice to Ninja.
What is the Event Propagation?
Let’s start with event propagation. This is the blanket term for both event bubbling and event capturing. Consider the typical markup to build a list of linked images, for a thumbnails gallery for example:
<ul>
<li><a href="..."><img src="..." alt=""></a>
<li><a href="..."><img src="..." alt=""></a>
...
<li><a href="..."><img src="..." alt=""></a>
</ul>
A click on an image does not only generate a click
event for the corresponding IMG
element, but also for the parent A
, for the grandfather LI
and so on, going all the way up through all the element’s ancestors, before terminating at the window
object.
In DOM terminology, the image is the event target, the innermost element over which the click originated. The event target, plus its ancestors, from its parent up through to the window
object, form a branch in the DOM tree. For example, in the image gallery, this branch will be composed of the nodes: IMG
, A
, LI
, UL
, BODY
, HTML
, document
, window
.
Note that
window
is not actually a DOM node but it implements theEventTarget
interface, so, for simplicity, we are handling it like it was the parent node of the document object.
This branch is important because it is the path along which the events propagate (or flow). This propagation is the process of calling all the listeners for the given event type, attached to the nodes on the branch. Each listener will be called with an event
object that gathers information relevant to the event (more on this later).
Remember that several listeners can be registered on a node for the same event type. When the propagation reaches one such node, listeners are invoked in the order of their registration.
It should also be noted that the branch determination is static, that is, it is established at the initial dispatch of the event. Tree modifications occurring during event processing will be ignored.
The propagation is bidirectional, from the window to the event target and back. This propagation can be divided into three phases:
- From the window to the event target parent: this is the capture phase
- The event target itself: this is the target phase
- From the event target parent back to the window: the bubble phase
What differentiates these phases is the type of listeners that are called.
The Event Capture Phase
In this phase only the capturer listeners are called, namely, those listeners that were registered using a value of true
for the third parameter of addEventListener:
el.addEventListener('click', listener, true)
If this parameter is omitted, its default value is false and the listener is not a capturer.
So, during this phase, only the capturers found on the path from the window to the event target parent are called.
The Event Target Phase
In this phase all the listeners registered on the event target will be invoked, regardless of the value of their capture flag.
The Event Bubbling Phase
During the event bubbling phase only the non-capturers will be called. That is, only the listeners registered with a value of false
for the third parameter of addEventListener()
:
el.addEventListener('click', listener, false) // listener doesn't capture
el.addEventListener('click', listener) // listener doesn't capture
Note that while all events flow down to the event target with the capture phase, focus
, blur
, load
and some others, don’t bubble up. That is, their travel stops after the target phase.
Therefore, at the end of the propagation, each listener on the branch has been called exactly once.
Event bubbling does not take place for every kind of event. During propagation, it is possible for a listener to know if an event bubbles by reading the .bubbles
Boolean property of the event
object.
The three event flow phase are illustrated in the following diagram from the W3C UIEvents specification.
Copyright © 2016 World Wide Web Consortium, (MIT, ERCIM, Keio, Beihang).
Accessing Propagation Information
I already mentioned the .bubbles
property of the event
object. There are a number of other properties provided by this object that are available to the listeners to access information relative to the propagation.
- e.target references the event target.
- e.currentTarget is the node on which the running listener was registered on. This is the same value of the listener invocation context, i.e, the value referenced by the
this
keyword. - We can even find out the current phase with e.eventPhase. It is an integer that refers to one the three
Event
constructor constantsCAPTURING_PHASE
,BUBBLING_PHASE
andAT_TARGET
.
Putting it into Practice
Let’s see the above concepts into practice. In the following pen, there are five nested square boxes, named b0
…b4
. Initially, only the outer box b0
is visible; the inner ones will show when the mouse pointer hovers over them. When we click on a box, a log of the propagation flow is shown on the table to the right.
See the Pen jmXdpz by SitePoint (@SitePoint) on CodePen.
It is even possible to click outside the boxes: in this case, the event target will be the BODY
or the HTML
element, depending on the click screen location.
Stopping Propagation
The event propagation can be stopped in any listener by invoking the stopPropagation method of the event object. This means that all the listeners registered on the nodes on the propagation path that follow the current target will not be called. Instead, all the other remaining listeners attached on the current target will still receive the event.
We can check this behavior with a simple fork of the previous demo, just inserting a call to stopPropagation()
in one of the listeners. Here we have prepended this new listener as a capturer to the list of callbacks registered on window
:
window.addEventListener('click', e => { e.stopPropagation(); }, true);
window.addEventListener('click', listener('c1'), true);
window.addEventListener('click', listener('c2'), true);
window.addEventListener('click', listener('b1'));
window.addEventListener('click', listener('b2'));
This way, whatever box is clicked, the propagation halts early, reaching only the capturer listeners on window
.
Stopping Immediate Propagation
As indicated by its name, stopImmediatePropagation throws the brakes on straight away, preventing even the siblings of the current listener from receiving the event. We can see this with a minimal change to the last pen:
window.addEventListener('click', e => { e.stopImmediatePropagation(); }, true);
window.addEventListener('click', listener('c1'), true);
window.addEventListener('click', listener('c2'), true);
window.addEventListener('click', listener('b1'));
window.addEventListener('click', listener('b2'));
Now, nothing is output in the log table, neither the c1
and c2
window capturers rows, because the propagation stops after the execution of the new listener.
Event Cancellation
Some events are associated with a default action that the browser executes at the end of the propagation. For instance, the click on a link element or the click on a form submit button causes the browser to navigate to a new page, or submit the form respectively.
It is possible to avoid the execution of such default actions with the event cancellation, by calling yet another method of the event object, e.preventDefault, in a listener.
Conclusion
With that, I hope to have shown you how event bubbling and event capturing work in JavaScript. If you have any questions or comments, I’d be glad to hear them in the discussion below.
References
- Document Object Model (DOM) Level 2 Events Specification
- W3C DOM4 – Events
- DOM – Living Standard – Events
- W3C UI Events – DOM Event Architecture
- MSN – Events and the DOM
This article was peer reviewed by Yaphi Berhanu and Dominic Myers. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!
Frequently Asked Questions (FAQs) about Event Bubbling in JavaScript
What is the main difference between event bubbling and event capturing?
Event bubbling and event capturing are two ways of event propagation in the HTML DOM API when an event occurs in an element inside another element, and both elements have registered a handle for that event. The main difference lies in the direction of propagation of the event relative to the DOM tree. In event bubbling, the event first triggers on the deepest target element, and then bubbles up to its parents. On the other hand, event capturing involves the event going down to the target element, starting from its parents.
How can I stop event bubbling in JavaScript?
In JavaScript, you can stop event bubbling by using the stopPropagation()
method. This method prevents further propagation of the current event in the capturing and bubbling phases. Here’s an example:element.addEventListener('click', function(event) {
event.stopPropagation();
});
In this code, if the element is clicked, the event does not bubble up to its parent elements.
What is the practical use of event bubbling in JavaScript?
Event bubbling can be very useful in handling certain events in JavaScript. For instance, if you have a parent element with several child elements, and you want to listen for a certain event on all of these elements, you can set the event listener on the parent and take advantage of event bubbling. This way, whenever the event is triggered on the child elements, it will bubble up to the parent and you can handle it there.
Can I use event bubbling and capturing at the same time?
Yes, you can use both event bubbling and capturing at the same time. This is known as event delegation. It’s a technique where you delegate the event handling to a parent element instead of setting the event listener on the individual child elements. This can be particularly useful when you have a large number of child elements.
What is the default behavior of event propagation in JavaScript?
The default behavior of event propagation in JavaScript is event bubbling. This means that by default, events will start from the target element and bubble up to the root of the document. However, you can change this behavior by using the addEventListener()
method with the useCapture
parameter set to true
, which will enable event capturing.
How does event bubbling work with nested elements?
When an event is fired from a nested element, the event will propagate up through the ancestors of the nested element in the DOM tree. This is event bubbling. Each ancestor in turn gets a chance to respond to the event. This propagation continues until it reaches the root of the document or until stopPropagation()
is called.
Can I prevent the default action of an event in event bubbling?
Yes, you can prevent the default action of an event in event bubbling by using the preventDefault()
method. This method cancels the event if it is cancelable, meaning the default action that belongs to the event will not occur.
What is the order of event propagation in JavaScript?
The order of event propagation in JavaScript is capturing phase, target phase, and bubbling phase. During the capturing phase, the event goes down to the element. The target phase is where the event has reached the target element. The bubbling phase is when the event bubbles up from the element.
How can I check if an event is bubbling or not?
You can check if an event is bubbling or not by using the bubbles
property of the event object. This property returns a boolean value indicating whether the event bubbles up through the DOM or not.
What is the difference between stopPropagation()
and stopImmediatePropagation()
?
Both stopPropagation()
and stopImmediatePropagation()
methods are used to stop the propagation of the event. The difference is that stopPropagation()
stops the event from bubbling up the event chain, while stopImmediatePropagation()
prevents other listeners of the same event from being called.