Events in LWC: DOM Events and CustomEvent

Data flows down from parent to child through @api properties. Information flows up through events. Because LWC uses the browser's own event system, everything you know about DOM events applies – plus a few rules that come from the shadow DOM. Get them right and your components stay loosely coupled and reusable.

The event object

Every handler receives an Event. The properties you'll use most:

Base components fire their own events with useful details: lightning-input's change carries event.detail.value (and event.target.value), lightning-combobox the chosen value, lightning-datatable the selected rows in rowselection.

Sending data up with CustomEvent

A child announces that something happened; the parent decides what to do about it. The child doesn't know or care who's listening:

<!-- ratingStars.html -->
<template>
    <template for:each={stars} for:item="star">
        <lightning-button key={star.value} label={star.label} data-value={star.value} onclick={handleRate}></lightning-button>
    </template>
</template>

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

export default class RatingStars extends LightningElement {
    @api value = 0;

    get stars() {
        return [1, 2, 3, 4, 5].map((n) => ({ value: n, label: n <= this.value ? '★' + n : '☆' + n }));
    }

    handleRate(event) {
        const rating = Number(event.currentTarget.dataset.value);
        // name: lowercase, no "on" prefix; data goes in detail
        this.dispatchEvent(new CustomEvent('rate', { detail: { rating } }));
    }
}

<!-- feedbackForm.html -->
<template>
    <p>How was your support experience?</p>
    <c-rating-stars value={rating} onrate={handleRate}></c-rating-stars>
    <p>{message}</p>
</template>

// feedbackForm.js
import { LightningElement } from 'lwc';

export default class FeedbackForm extends LightningElement {
    rating = 0;
    message = 'Not rated yet';

    handleRate(event) {
        this.rating = event.detail.rating;           // the parent owns the value…
        this.message = this.rating >= 4 ? 'Thank you!' : 'Sorry – we will follow up.';
    }                                                // …and passes it back down via value={rating}
}

How was your support experience?
[☆1] [☆2] [☆3] [☆4] [☆5]
Not rated yet

› click “☆4”
How was your support experience?
[★1] [★2] [★3] [★4] [☆5]
Thank you!

› click “★2”
How was your support experience?
[★1] [★2] [☆3] [☆4] [☆5]
Sorry – we will follow up.

• Event names are lowercase with no spaces, no hyphens and no on prefix: the parent writes onrate for an event called rate.
• Put primitives or new objects in detail. Passing your own internal object lets the parent mutate the child's state – send a copy.

bubbles and composed

By default a CustomEvent doesn't bubble at all – only listeners on the child's host element (like onrate above) hear it. Two options change that:

Here's bubbling inside one template – a single handler on a wrapper hears every child's event:

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

export default class TaskItem extends LightningElement {
    @api taskId;
    @api label;

    handleDone() {
        this.dispatchEvent(new CustomEvent('taskdone', { bubbles: true, detail: { taskId: this.taskId } }));
    }
}

<!-- taskItem.html -->
<template>
    <lightning-button label={label} onclick={handleDone}></lightning-button>
</template>

// taskBoard.js
import { LightningElement } from 'lwc';

export default class TaskBoard extends LightningElement {
    tasks = [
        { id: 't1', label: 'Call Acme' },
        { id: 't2', label: 'Send quote' },
        { id: 't3', label: 'Book demo' },
    ];

    handleTaskDone(event) {
        // one handler on the wrapper; target is the c-task-item that fired the event
        const { taskId } = event.detail;
        this.tasks = this.tasks.filter((t) => t.id !== taskId);
    }

    get remaining() {
        const n = this.tasks.length;
        return `${n} ${n === 1 ? 'task' : 'tasks'} left`;
    }
}

<!-- taskBoard.html -->
<template>
    <div ontaskdone={handleTaskDone}>
        <template for:each={tasks} for:item="task">
            <c-task-item key={task.id} task-id={task.id} label={task.label}></c-task-item>
        </template>
    </div>
    <p>{remaining}</p>
</template>

[Call Acme] [Send quote] [Book demo]
3 tasks left

› click “Send quote”
[Call Acme] [Book demo]
2 tasks left

› click “Call Acme”
[Book demo]
1 task left

Event delegation in your own template

The same idea works with ordinary DOM events: native events like click bubble, so one handler on a container can serve a whole list. Read data-* from the element that was actually clicked:

// filterChips.js
import { LightningElement } from 'lwc';

export default class FilterChips extends LightningElement {
    options = ['Hot', 'Warm', 'Cold'];
    selected = new Set();
    summary = 'No filters';

    get chips() {
        return this.options.map((o) => ({ name: o, label: this.selected.has(o) ? `✓ ${o}` : o }));
    }

    handleClick(event) {
        const name = event.target.dataset.name;      // the clicked chip, not the container
        if (!name) return;                           // a click on the gap between chips
        const next = new Set(this.selected);
        if (next.has(name)) next.delete(name);
        else next.add(name);
        this.selected = next;                        // new Set → re-render
        this.summary = next.size ? `Showing: ${[...next].join(', ')}` : 'No filters';
    }
}

<!-- filterChips.html -->
<template>
    <div onclick={handleClick}>
        <template for:each={chips} for:item="chip">
            <lightning-button key={chip.name} label={chip.label} data-name={chip.name}></lightning-button>
        </template>
    </div>
    <p>{summary}</p>
</template>

[Hot] [Warm] [Cold]
No filters

› click “Hot”
[✓ Hot] [Warm] [Cold]
Showing: Hot

› click “Cold”
[✓ Hot] [Warm] [✓ Cold]
Showing: Hot, Cold

› click “✓ Hot”
[Hot] [Warm] [✓ Cold]
Showing: Cold

With delegation, here event.target (what was clicked) is the right property, whereas in a handler attached to each button you'd use currentTarget.

Practice

Summary