Level: IntermediateLightning Web Components

LWC Custom Events: Child to Parent Communication Made Simple

Updated 8 min read
LWC Custom Events featured image: title card with an LWC code example

LWC Custom Events are how a child component tells its parent that something happened, such as “a course was selected” or “a form was saved”. The child creates a CustomEvent, adds any data in its detail, and dispatches it. The parent listens with an on handler in its template, just like it listens to a button click.

In this post, you will learn how to create and dispatch events, how to name them, what goes in detail, and when to use the bubbles and composed options. It builds on LWC parent to child communication, LWC loops and Salesforce Platform Events, which use the same publish and listen idea on the server.

What are LWC Custom Events?

LWC Custom Events are standard browser CustomEvent objects that a component fires with this.dispatchEvent. Each event has a name, such as enrol, and an optional detail object with data. The parent handles it by adding onenrol={handleEnrol} to the child tag.

Think of a student raising a hand in class. The student does not walk to the teacher’s desk and change the timetable. Instead, they raise a hand and say “I have a question about chapter 3”. The teacher decides what to do. The raised hand is the event, and “chapter 3” is the detail.

Why LWC Custom Events Matter

Data flows down with @api, but actions start in children. Here is why LWC Custom Events matter at Bright Path Tutors.

  • First, a course card must tell the catalog when a tutor clicks Enrol.
  • Also, a search box must tell its parent the new search text.
  • Next, a form must report that it saved, so the parent can refresh.
  • Children stay reusable, because they do not know who their parent is.
  • Finally, events keep the parent in charge of shared data.

So events complete the two-way conversation between components.

How LWC Custom Events Work

LWC Custom Events follow a clear path. First, something happens in the child, such as a button click. Next, the child creates new CustomEvent(‘enrol’, { detail: { courseId } }). Then it calls this.dispatchEvent(event). After that, the event travels to the parent, which listens with onenrol={handleEnrol} on the child tag. Finally, the parent’s handler reads event.detail and updates its own data.

LWC Custom Events diagram showing action, create, dispatch, listen and handle
How an event travels from child to parent.

Creating an Event

Create an event with new CustomEvent(name, options). The name is a plain string, such as enrol or search.

Naming Rules

Event names should be lowercase, with no spaces and no hyphens or uppercase letters. Do not start the name with “on”, because the parent adds “on” when listening.

The detail Property

detail carries the data, such as a record Id. Prefer simple values or a copy of the data, so the parent cannot change the child’s internal objects.

bubbles and composed

By default, an event goes only to the direct parent. bubbles: true lets it rise through the parent’s own DOM, and composed: true lets it cross shadow boundaries to higher components. Use these only when you really need them.

Listening in JavaScript

A parent can also listen with addEventListener, for example in connectedCallback. However, the template on-handler is simpler and cleans up automatically.

Event Options at a Glance

The table below sums up the event options.

OptionDefaultWhat it does
detailnullCarries data to the listener
bubblesfalseRises through the DOM tree
composedfalseCrosses shadow DOM boundaries
cancelablefalseLets listeners call preventDefault

@api Property vs Custom Event

The table below compares the two directions of communication.

Feature@api propertyCustom event
DirectionParent to childChild to parent
CarriesData for displayNews that something happened
Who owns dataParentParent, after handling
CouplingChild knows nothing of parentChild knows nothing of parent
Examplecourse={course}onenrol={handleEnrol}

When to use which follows the direction. Send data down with @api properties. Send news up with LWC Custom Events.

LWC Custom Events diagram comparing @api properties and custom events
@api property vs custom event.

A Real LWC Custom Events Example

Let’s add LWC Custom Events to Bright Path Tutors. Each course card fires an enrol event, and the catalog keeps a running list of chosen courses.

Step 1: The Child Fires the Event

// courseCard.js
import { LightningElement, api } from 'lwc';

export default class CourseCard extends LightningElement {
    @api course;

    handleEnrolClick() {
        const evt = new CustomEvent('enrol', {
            detail: { courseId: this.course.Id, name: this.course.Name }
        });
        this.dispatchEvent(evt);
    }
}
<!-- courseCard.html -->
<template>
    <div class="slds-box slds-m-bottom_small">
        {course.Name}
        <lightning-button label="Enrol" onclick={handleEnrolClick}
            class="slds-m-left_small"></lightning-button>
    </div>
</template>

When the tutor clicks Enrol, the card creates an enrol event. Its detail holds the course Id and name, both simple values.

Step 2: The Parent Listens

<!-- courseCatalog.html -->
<template>
    <template for:each={courses} for:item="c">
        <c-course-card key={c.Id} course={c} onenrol={handleEnrol}></c-course-card>
    </template>
    <p>Chosen: {chosenText}</p>
</template>
// courseCatalog.js
import { LightningElement } from 'lwc';

export default class CourseCatalog extends LightningElement {
    courses = [
        { Id: 'a01A', Name: 'Apex Basics' },
        { Id: 'a01B', Name: 'SOQL Basics' }
    ];
    chosen = [];

    handleEnrol(event) {
        const { courseId, name } = event.detail;
        if (!this.chosen.some(c => c.courseId === courseId)) {
            this.chosen = [...this.chosen, { courseId, name }];
        }
    }

    get chosenText() {
        return this.chosen.length ? this.chosen.map(c => c.name).join(', ') : 'None yet';
    }
}

The parent listens with onenrol on each card. Then handleEnrol reads the detail, skips duplicates, and assigns a new array, so the text updates.

Step 3: See It Work

Here is what the catalog shows after clicking Enrol on both cards.

Apex Basics [Enrol]
SOQL Basics [Enrol]
Chosen: Apex Basics, SOQL Basics

The cards never touched the parent’s list. They only announced what happened.

LWC Custom Events with bubbles and composed

If a grandparent needs the event, you could set bubbles: true and composed: true. However, that exposes the event to the whole page. A cleaner pattern is for the parent to handle the event and fire its own event upward. For unrelated components, use Lightning Message Service, which a later post covers.

Common Mistakes with LWC Custom Events

  • Naming events with uppercase letters or hyphens.
  • Starting the event name with “on”, such as onenrol.
  • Passing the child’s internal objects in detail.
  • Turning on bubbles and composed by default.
  • Changing the parent’s data from the child instead of firing an event.

Best Practices for LWC Custom Events

  • Use short, lowercase, meaningful event names.
  • Put only the data the parent needs in detail.
  • Keep bubbles and composed off unless truly needed.
  • Handle events in the template with on-handlers.
  • Use Lightning Message Service for unrelated components.

Practice Task

Add a remove event to each chosen course in the parent’s list, so a small child chip can ask the catalog to remove it. Hint: create a chip component that fires remove with the courseId, and filter the array in the parent.

Most Asked Interview Questions on LWC Custom Events

Event questions appear in almost every LWC interview. Here are the 21 questions asked most about LWC Custom Events.

Basic Questions on LWC Custom Events

Q1: How does a child send data to a parent in LWC?

It dispatches a CustomEvent with the data in detail, and the parent handles it.

Q2: How do you create a custom event?

Use new CustomEvent(‘name’, { detail: data }).

Q3: How do you fire it?

Call this.dispatchEvent(event) in the child.

Q4: How does the parent listen?

It adds on plus the event name on the child tag, such as onenrol={handleEnrol}.

Q5: Where is the event data?

In event.detail.

Q6: What are the naming rules for events?

Use lowercase letters with no spaces, hyphens or “on” prefix.

Q7: Does an event bubble by default?

No, so it reaches only the direct parent unless you set bubbles.

Code and Scenario Questions on LWC Custom Events

Q8: What does composed: true do?

It lets the event cross shadow DOM boundaries to higher components.

Q9: Why avoid putting objects in detail?

Because the parent could change them, so send primitives or a copy.

Q10: How do you pass two values in one event?

Put both in an object, such as detail: { courseId, name }.

Q11: Can a parent listen with JavaScript instead of markup?

Yes, with addEventListener, but you must remove the listener yourself.

Q12: How do you reach a grandparent?

Have the parent handle the event and fire a new one, or use bubbles and composed.

Q13: How do unrelated components communicate?

They use Lightning Message Service instead of DOM events.

Q14: What is event.target in a parent handler?

It is the child component that dispatched the event.

Advanced Questions on LWC Custom Events

Q15: Why keep bubbles and composed off by default?

Because events then stay private, so other components cannot rely on them.

Q16: What does cancelable do?

It lets listeners call preventDefault, so the child can check if an action was cancelled.

Q17: Can an event carry a function?

It can, but it is a poor pattern, so send data instead.

Q18: How do Aura parents handle LWC events?

They use an on-attribute in the Aura markup and read event.getParam(‘…’) for detail values.

Q19: How do you test that a component fires an event?

In Jest, add a listener to the element, click the button, and assert the handler was called.

Q20: Why is one-way data flow with events useful?

Because only the parent changes shared data, so bugs are easier to trace.

Q21: When would you choose LMS over events?

When the components are not in the same parent and child chain, such as utility bar items.

Official Resources

Quick Recap

  • LWC Custom Events send news from a child to its parent.
  • Create them with new CustomEvent and fire them with dispatchEvent.
  • Use lowercase names without the “on” prefix.
  • The parent listens with on plus the event name and reads event.detail.
  • Keep bubbles and composed off unless truly needed.

What’s Next?

Some components are not parent and child at all. Next, read our guide to Lightning Message Service in LWC.