Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 39 ยท Shadow DOM

Events and the Shadow Boundary

Learn how events cross the shadow boundary: event retargeting, the composed and bubbles flags, composedPath(), and how to dispatch custom events from a component.

Events are how users interact with your component and how your component talks back to the page. Shadow DOM changes the rules of event propagation slightly, to keep the internals private. Two ideas matter: retargeting (outside code sees the host, not the internal element) and the composed flag (which decides whether an event can leave the shadow tree at all).

Events bubble through the shadow tree

A click inside a shadow tree starts at the clicked element and bubbles up through its ancestors in the shadow tree, up to the shadow root, then out through the host and on to the page, as if the shadow root were just another parent. Listeners can be placed anywhere along that path.

Retargeting

When the event reaches listeners outside the shadow root, event.target is changed to the host. From outside, the page cannot see which internal element was clicked. That hides implementation details, and also means your outside listener cannot rely on event.target to learn which inner button fired.

Retargeting in action

Inside the shadow root, e.target.id is yes or no. In the document listener, e.target.localName is button-pair: the host. The composedPath() call reveals the full path, including internal nodes, which is allowed for open roots (for closed roots, internal nodes are removed from the path).

The composed flag

Not every event crosses the boundary. Each event has a composed property:

  • composed: true: the event propagates out of the shadow tree to the page.
  • composed: false: the event stops at the shadow root; outsiders never see it.

Most UI events that the browser itself generates are composed: click, dblclick, mousedown, mouseup, keydown, keyup, focus, blur (the latter two do not bubble but are composed), input and beforeinput, pointer and touch events, wheel. A few are not composed: load, error (resource events), select, change, and slotchange. change is a famous case: a native <input> inside a shadow root fires change that never leaves it, so your component must re-dispatch.

Dispatching your own events

Use CustomEvent to tell the world something happened. Two properties decide whether the page can hear it:

Option Meaning
bubbles: true The event travels up through ancestors
composed: true The event is allowed to cross the shadow boundary
detail Any data you want to pass along

For events dispatched on the host element itself (this.dispatchEvent(...)), the host is already outside the shadow tree, so composed is not needed to reach the page. It matters when you dispatch from an element inside the shadow tree and want listeners outside to receive it.

A component with its own event

The page listens for a clear, meaningful event called rate, not for raw clicks on internal buttons. This is the recommended pattern: expose semantic events, not implementation events.

Re-dispatching native events

Because change is not composed, forward it yourself when a component wraps an input:

JavaScript
this.input.addEventListener("change", () => {
  this.dispatchEvent(new Event("change", { bubbles: true }));
});

Dispatched on the host with bubbles: true, it reaches the page and parent elements.

Event handling patterns

  • Listen on the shadow root with delegation (e.target.closest(...)) rather than on every inner element. It handles dynamically added content and keeps code short.
  • Use composedPath()[0] if an outside listener must know the real origin (only works for open roots, and with the usual caution about breaking encapsulation).
  • Name events like native ones: lowercase words, - separated for multiple words (for example item-selected), and document them as part of your public API.
  • Do not rely on e.target identity across the boundary; it is intentionally hidden.
flowchart LR
  A["click on inner button"] --> B["bubbles in shadow tree"]
  B --> C["shadow root"]
  C -->|"composed: true"| D["host (target retargeted)"]
  D --> E["page ancestors, document"]
  C -->|"composed: false"| F["stops here"]

Retargeting happens at the shadow root, and composed decides whether the event leaves it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does event.target show to a listener outside the shadow root?

    Retargeting replaces internal targets with the host so internals stay hidden.
  2. 2. What does composed: true do on an event?

    composed controls whether the event propagates out of the shadow tree; bubbles is separate.
  3. 3. Which native event does not cross a shadow boundary?

    change is not composed, so components wrapping inputs should re-dispatch it.
  4. 4. Which method reveals the full propagation path of an event, including internal nodes of open roots?

    composedPath() returns the nodes the event travels through; closed roots hide their internals.

Summary

  • Events bubble out of a shadow tree through the host, but are retargeted to the host for outside listeners.
  • composed decides whether an event can leave the shadow tree; most UI events are composed, change is not.
  • Dispatch semantic CustomEvents with detail, and add bubbles and composed if you fire them from inner nodes.
  • Use delegation on the shadow root and re-dispatch non-composed native events.
  • composedPath() shows the full path for open roots.

Next: Declarative Shadow DOM