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.

When you create an event, define event propagation behavior using two properties on the event, bubbles and composed.

• Event.bubbles

  A Boolean value indicating whether the event bubbles up through the DOM or not. Defaults to false.

• Event.composed

  A Boolean value indicating whether the event can pass through the shadow boundary. Defaults to false.

To get information about the event, use these properties and method of the Event Web API.

• Event.target

  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.target changes 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-button> always receives my-button as the target, even if the click happened on the button element.

• Event.currentTarget

  As the event traverses the DOM, this property always refers to the element to which the event handler has been attached.

• Event.composedPath()

  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-app composes c-parent, which in turn composes c-child.

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 onclick handler.

The example fires an event, buttonclick, from c-child when the button is clicked. Event listeners are attached for the custom event on the following elements:

• body
• c-app host
• c-parent
• div.wrapper
• c-child host

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 only.

Inspecting c-child handlers returns these values on the event.

• event.currentTarget = c-child
• event.target = c-child

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 c-child and div.wrapper can react to the event.

The event handlers return the following.

c-child handler

• event.currentTarget = c-child
• event.target = c-child

div.childWrapper handler

• event.currentTarget = div.childWrapper
• event.target = c-child

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 eventBubbling component in the lwc-recipes repo. The component hierarchy from child to grandparent is c-contact-list-item-bubbling -> lightning-layout-item -> c-event-bubbling.

  The c-contact-list-item-bubbling component dispatches a custom event called contactselect with bubbles: true.

  The event listener, oncontactselect is on its parent, lightning-layout-item, and the event is handled in its grandparent, c-event-bubbling.

The event bubbles up through the DOM, crosses the shadow boundary, and continues bubbling up through the DOM to the document root.

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 onmydomain__myevent.

Lightning web components don’t use this configuration.

See Also

• Javascript.info: Introduction to Events: Bubbling and capturing
• Shadow DOM