Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Events and Slots

Events in Lit: Listening and Dispatching

Handle DOM events with @ bindings in Lit and dispatch your own CustomEvents, including bubbles, composed, detail payloads, retargeting and event naming conventions.

A web component talks to the outside world in two directions. Data flows down through attributes and properties. Notifications flow up through DOM events. Lit gives you a pleasant syntax for listening to events inside templates, and the platform gives you CustomEvent for sending your own.

This lesson covers both halves, then the two options that decide whether an event can escape a shadow root: bubbles and composed.

Listening with @ bindings

In a Lit template, @eventname=${handler} adds an event listener. Lit calls the handler with this bound to the component (the host), so you can use ordinary methods without .bind.

@click and event arguments

The handler receives the native Event object. Event names are case-sensitive and match the DOM name, so @keydown, @input, @pointerdown and custom names such as @item-selected all work.

Event listener options go in an object: @scroll=${{ handleEvent: this._onScroll, passive: true }}. The handleEvent form is a standard DOM listener object, and Lit passes it straight to addEventListener.

Creating and dispatching a CustomEvent

To tell the outside world that something happened, create a CustomEvent and call this.dispatchEvent(...) on the component. The event's detail can carry any payload.

dispatchEvent with detail

Notice that the consumer uses a plain addEventListener. Inside another Lit template the same listener is written @quantity-change=${handler}.

Naming events

  • Use lowercase, hyphen-separated names (quantity-change, item-selected). They work in HTML attributes in other frameworks and avoid collisions with built-in names.
  • Prefer a past-tense or -change name for notifications ("something happened"), and a verb for requests you expect someone to handle.
  • If your element wraps a native control, keep the native event names (input, change) where their meaning is the same.

bubbles and composed

Two flags control how far an event travels, and they are the most common reason that "my event does not arrive".

Option Default Meaning
bubbles false Travel up through ancestors (the event path), like click
composed false Be allowed to cross a shadow root boundary

A custom event with neither flag fires only on the element it was dispatched on. That is fine for the quantity picker above, where the listener sits on the component itself. It is not fine when a button inside component A's shadow DOM wants to notify the page.

Crossing shadow boundaries

Only the last button reaches document. The event is dispatched on <inner-button>, which lives inside <outer-box>'s shadow root. bubbles lets it move up, but without composed it stops at the shadow root's edge; with both it escapes into the light DOM.

How far does an event go?

Neither flag Only the dispatching element
bubbles Up to the shadow root edge
bubbles + composed Out to the page

Native click and input are both flags on.

1 / 2

Guidance: dispatch on the host (this), keep events narrow by default, and add bubbles and composed only when ancestors beyond your own parent should hear it. Many design systems make every public event bubbles: true, composed: true for convenience; that is a valid choice if you document it.

Retargeting: who is event.target?

When an event leaves a shadow root, the browser retargets it: to listeners outside, event.target is the host element, not the internal node. That protects encapsulation. Inside the shadow root, listeners still see the real target. If you need the true origin (for example for analytics) use event.composedPath()[0].

Retargeting

click is a native event that is both bubbles and composed, which is why the page can listen on the host at all.

Passing the original event, or a better one

For a component that wraps a native control, you have two options:

  1. Let the native event escape. Native input events are composed, so they already reach the page. change is not composed, so a wrapper has to re-dispatch it.
  2. Dispatch a custom event with a useful detail, and keep the native one internal. This hides the markup and gives consumers typed data.
JavaScript
_onChange(e) {
  // `change` does not cross shadow boundaries, so announce it ourselves
  this.value = e.target.value;
  this.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
}

Use new Event(...) when there is no payload and new CustomEvent(...) when there is.

Cancelable events

Setting cancelable: true lets a listener call event.preventDefault(). dispatchEvent returns false if anyone did, so the component can skip its default action. This is how you model "before" events such as before-close.

Cancelable event

Common mistakes

  • Dispatching from a child node with no composed flag and wondering why the page never hears it.
  • Forgetting that this in @click=${this.handler} is already the host; adding .bind(this) is harmless but redundant.
  • Putting a whole component instance in detail. Send small, serializable data.
  • Using camelCase event names (itemSelected). They are legal but unconventional; stick to kebab-case.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A button inside a component's shadow DOM dispatches new CustomEvent('saved'). A listener on document never fires. Why?

    Without bubbles it does not travel up, and without composed it cannot cross the shadow root boundary.
  2. 2. What is event.target for a page-level listener when a click originated on an internal button of a component?

    Retargeting hides the shadow internals; composedPath() still reveals the real origin.
  3. 3. How do you pass data with a custom event?

    CustomEvent takes a detail option holding any value.
  4. 4. What does dispatchEvent return for a cancelable event whose listener called preventDefault()?

    A false return signals that the default action should be skipped.

Summary

  • Listen with @event=${handler}; this is the host.
  • Send notifications with this.dispatchEvent(new CustomEvent(name, { detail })).
  • Add bubbles to travel up and composed to cross shadow roots; use the narrowest reach that works.
  • Retargeting hides internals from outside listeners; composedPath() shows the real origin.
  • Use cancelable for "before" events that a listener may veto.

Next: Slots and Composition