Configure Event Propagation
After an event is fired, it can propagate up through the DOM. To understand where events can be handled, understand how they propagate.
Events bubble up through the DOM; that’s how children and parents communicate—props down, events up. When an event bubbles, it becomes part of your component's API and every consumer along the event's path must understand the event. It’s important to understand how bubbling works so you can choose the most restrictive bubbling configuration that works for your component.
Lightning web component events propagate according to the same rules as DOM events. Lightning web components use only the bubbling phase. Dispatching events or adding listeners to the capture phase isn't supported. Simply think of the event’s path as starting with your component and then moving to its parent, and then grandparent, and so on.
Event targets don’t propagate beyond the shadow root of the component instance. From outside the component, all event targets are the component itself. However, inside the shadow tree, you can handle events from specific targets in the tree. Depending on where you attach a listener for the event, and where the event happens, you can have different targets.
This content is adapted from the Salesforce Developer blog post, How Events Bubble in Lightning Web Components.
When you create an event, define event propagation behavior using two properties on the event,
A Boolean value indicating whether the event bubbles up through the DOM or not. Defaults to
A Boolean value indicating whether the event can pass through the shadow boundary. Defaults to
To get information about the event, use these properties and method of the Event Web API.
The element that dispatched the event.
Each component’s internal DOM is encapsulated in a shadow DOM. The shadow boundary is the line between the regular DOM (also called the light DOM) and the shadow DOM. If an event bubbles up and crosses the shadow boundary, the value of
Event.targetchanges to represent an element in the same scope as the listener. Event retargeting preserves component encapsulation and prevents exposing a component’s internals.
For example, a click listener on
my-buttonas the target, even if the click happened on the
As the event traverses the DOM, this property always refers to the element to which the event handler has been attached.
An array of the event targets on which listeners are invoked as the event traverses the DOM.
A static composition doesn't use slots. In this simple example,
c-parent, which in turn composes
The parent component in the app handles the button click.
The parent component contains a wrapper with a child component, both listening for the button click event.
The child component contains the button with the
The example fires an event,
c-child when the button is clicked. Event listeners are attached for the custom event on the following elements:
The flattened tree looks like this:
The default configuration. The event doesn’t bubble up through the DOM and doesn’t cross the shadow boundary. The only way to listen to this event is to add an event listener directly on the component that dispatches the event.
This configuration is recommended because it’s the least disruptive and provides the best encapsulation for your component.
The event bubbles up to
c-child handlers returns these values on the event.
From here, you can start implementing more permissive configurations, as shown in the next few sections.
The event bubbles up through the DOM, but doesn’t cross the shadow boundary. As a result, both
div.wrapper can react to the event.
The event handlers return the following.
There are two use cases for using this configuration.
Create an internal event
To bubble an event inside the component’s template, dispatch the event on an element in the template. The event bubbles up to the element’s ancestors inside the template only. When the event reaches the shadow boundary, it stops.
The event must be handled in
myComponent.js. Handlers in the containing component don’t execute because the event doesn’t cross the shadow boundary.
Send an event to a component’s grandparent
If a component is passed into a slot, and you want to bubble an event from that component to the template that contains it, dispatch the event on the host element. The event is visible only in the template that contains your component.
Let’s look at sample code abridged from the
eventBubblingcomponent in the lwc-recipes repo. The component hierarchy from child to grandparent is
c-contact-list-item-bubbling -> lightning-layout-item -> c-event-bubbling.
c-contact-list-item-bubblingcomponent dispatches a custom event called
The event listener,
oncontactselectis on its parent,
lightning-layout-item, and the event is handled in its grandparent,
The event bubbles up through the DOM, crosses the shadow boundary, and continues bubbling up through the DOM to the document root.
If an event uses this configuration, the event type becomes part of the component’s public API. It also forces the consuming component and all of its ancestors to include the event as part of their APIs.
Because this configuration bubbles your event all the way to the document root, it can cause name collisions. Name collisions can cause the wrong event listeners to fire.
If you do use this configuration, prefix your event type with a namespace, like
mydomain__myevent. The HTML event listener would have the awkward name
Lightning web components don’t use this configuration.