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 receivesmy-button
as the target, even if the click happened on thebutton
element.<!-- myButton.html --> <template> <button>{label}</button> </template>
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.
Static Composition
A static composition doesn't use slots. In this simple example, c-app
composes c-parent
, which in turn composes c-child
.
<c-app onbuttonclick={handleButtonClick}></c-app>
The parent component in the app handles the button click.
<!-- app.html -->
<template>
<h2>My app</h2>
<c-parent onbuttonclick={handleButtonClick}></c-parent>
</template>
The parent component contains a wrapper with a child component, both listening for the button click event.
<!-- parent.html -->
<template>
<h3>I'm a parent component</h3>
<div class='wrapper' onbuttonclick={handleButtonClick}>
<c-child onbuttonclick={handleButtonClick}></c-child>
</div>
</template>
The child component contains the button with the onclick
handler.
<!-- child.html -->
<template>
<h3>I'm a child component</h3>
<button onclick={handleClick}>click me</button>
</template>
// child.js
handleClick() {
const buttonclicked = new CustomEvent('buttonclick', {
//event options
});
this.dispatchEvent(buttonclicked);
}
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
hostc-parent
div.wrapper
c-child
host
The flattened tree looks like this:
<body> <!-- Listening for buttonclick event -->
<c-app> <!-- Listening for buttonclick event -->
#shadow-root
| <h2>My app</h2>
| <c-parent> <!-- Listening for buttonclick event -->
| #shadow-root
| | <h3>I'm a parent component</h3>
| | <div class="wrapper"> <!-- Listening for buttonclick event -->
| | <c-child> <!-- Listening for buttonclick event -->
| | #shadow-root
| | | <h3>I'm a child component</h3>
| | | <button>click me</button>
| | </c-child>
| | </div>
| </c-parent>
</c-app>
</body>
bubbles: false
and composed: false
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.
<body>
<c-app>
#shadow-root
| <c-parent>
| #shadow-root
| | <div class="wrapper">
| | <c-child> <!-- Event bubbles up here -->
| | #shadow-root
| | | <h3>I'm a child component</h3>
| | | <button>click me</button>
| | </c-child>
| | </div>
| </c-parent>
</c-app>
</body>
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.
bubbles: false
and composed: false
.bubbles: true
and composed: false
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.
<body>
<c-app>
#shadow-root
| <c-parent>
| #shadow-root
| | <div class="wrapper"> <!-- Event bubbles up here -->
| | <c-child> <!-- Event bubbles up here -->
| | #shadow-root
| | | <h3>I'm a child component</h3>
| | | <button>click me</button>
| | </c-child>
| | </div>
| </c-parent>
</c-app>
</body>
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.
// myComponent.js this.template.querySelector('div') .dispatchEvent( new CustomEvent('notify', { bubbles: true }) );
- 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.
<!-- container.html --> <template> <!-- handleNotify doesn’t execute --> <c-my-component onnotify={handleNotify}></c-my-component> </template>
- 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 calledcontactselect
withbubbles: true
. - The event listener,
oncontactselect
is on its parent,lightning-layout-item
, and the event is handled in its grandparent,c-event-bubbling
.<!-- eventBubbling.html --> <template> <lightning-card title="EventBubbling" icon-name="standard:logging"> <template if:true={contacts.data}> <lightning-layout class="slds-var-m-around_medium"> <!-- c-contact-list-item-bubbling emits a bubbling event so a single listener on a containing element works --> <lightning-layout-item class="wide" oncontactselect={handleContactSelect} > <template for:each={contacts.data} for:item="contact"> <c-contact-list-item-bubbling class="slds-show slds-is-relative" key={contact.Id} contact={contact} ></c-contact-list-item-bubbling> </template> </lightning-layout-item> </lightning-layout> </template> </lightning-card> </template>
-
// contactListItemBubbling.js import { LightningElement, api } from 'lwc'; export default class ContactListItemBubbling extends LightningElement { @api contact; handleSelect(event) { // Prevent default behavior of anchor tag click which is to navigate to the href url event.preventDefault(); const selectEvent = new CustomEvent('contactselect', { bubbles: true }); this.dispatchEvent(selectEvent); } }
bubbles: true
and composed: true
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.
<body> <!-- Event bubbles up here -->
<c-app> <!-- Event bubbles up here -->
#shadow-root
<c-parent> <!-- Event bubbles up here -->
#shadow-root
<div class="wrapper"> <!-- Event bubbles up here -->
<c-child> <!-- Event bubbles up here -->
#shadow-root
</c-child>
</div>
</c-parent>
</c-app>
</body>
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
.
bubbles: false
and composed: true
Lightning web components don’t use this configuration.
No comments:
Post a Comment