Child component events

Your components can send an event just like the standard browser HTML elements. In fact, Lightning Web Components utilize the standard CustomEvent API, which you can find documented at https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent. In the sample code included in this chapter, the race component (child) is contained by the raceCalendar component (parent). The race component sends an event to the raceCalendar component when the user clicks it. This type of event can only bubble up through components that are contained within the component's parent-child hierarchy.

The following example shows a fragment of HTML from the raceCalendar component that references the race component. Using the onselect attribute, it passes an event handler defined in its controller for the clicked event exposed by the race component.

The raceCalendar.html file is as follows:

...
<c-race
  race-id={race.Id}
  name={race.Name} 
  race-date={race.RaceDate}
  completed={race.Completed} 
  location={race.Location} 
  selected={race.Selected}
  onselect={handleSelect}>
...

The following example shows the handler referenced in the preceding code block. The event parameter is based on the standard definition defined at https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent. The detail property is set by the race component and, in this case, contains the ID of the Race record the user clicked. The raceCalendar.js file is as follows:

handleSelect(event) {
    const raceId = event.detail;
    ...
}

Let's now review how the race component exposed the select event used in the preceding code. This component has encapsulated the behavior of what the user clicks, so that the parent component does not have to concern itself with such details. In the following fragment, from the race component, you can see that it is using the lightning-tile component and setting its own event handler on the standard click event. Because events bubble upward, clicking on it and its children will be result in an event. The race.html file is as follows:

<lightning-tile label={name} href="/" type="media" 
    class={raceStyle} onclick={raceClicked}>
     <lightning-avatar slot="media" fallback-icon-name={raceIcon}> .    </lightning-avatar>
     <ul class="slds-list_vertical slds-has-dividers_right">
         <li class="slds-item">{location}</li>
         <li class="slds-item">{raceDate}</li>
     </ul>
</lightning-tile>

The following race.js code shows how the internal click handler receives the event, uses state contained by the component (raceId), and then dispatches (sends) the event. The race.js file is as follows:

raceClicked() {
   this.dispatchEvent(
     new CustomEvent('select', { detail: this.raceId }));
}

Note that the race component did not have to explicitly declare that it sends the select event. The framework simply matches the parent component's use of the onselect attribute with the firing of the event by the name used, prefixing the attribute with on by convention.

The standard documentation for fire events includes a very important security guideline I also want to emphasize here the fact that when you assign the detail property to CustomEvent, do not use an object reference – or at least use a cloned reference to an object if you do. The reason for this is due to JavaScript passing objects by reference. So, if you pass an instance of an internal object (for example, part of your component's internal state), you risk the handler for the event modifying that object via this reference. This would break best practices regarding encapsulation and potentially result in hard-to-find bugs in your code. You can read more about managing events at https://developer.salesforce.com/docs/component-library/documentation/lwc/lwc.events_create_dispatch.

Table of Contents for Child component events

Create new playlist

Sign In

Sign Up

Table of Contents for
Child component events