Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 39 ยท Events and Properties

Event Retargeting and Composed Events

Learn how events behave at shadow DOM boundaries: retargeting, composed vs non-composed events, composedPath(), and how to design events that cross cleanly.

Shadow DOM hides a component's internals from the page. Events have to respect that hiding too. If a user clicks a button deep inside a shadow root, listeners outside should not be able to see which private element was clicked. The browser enforces this with event retargeting, and decides which events may leave at all with the composed flag.

This lesson explains both ideas, shows how to inspect the real path with composedPath(), and gives you rules for designing events that behave well across shadow boundaries.

What retargeting does

When an event leaves a shadow tree, event.target is rewritten to the shadow host for any listener outside that tree. Inside the tree, listeners still see the real inner element.

Seeing event.target change

Click the button. The listener inside the shadow root reports button#inner; the document listener reports x-box. The page never learns that a button was involved, so you can rename or replace that button later without breaking anyone.

Which events cross the boundary?

An event leaves the shadow tree only if it is composed. The rules:

  • Most UI events the browser fires from real user input (click, pointerdown, keydown, focus-family, input) are composed.
  • Some events are not composed: mouseenter, mouseleave, load, error, and the change event of form controls. Many selection and media events also stop at the boundary.
  • Your own events are not composed by default. new CustomEvent("x") stays inside the shadow tree unless you set composed: true.

A very common surprise: a custom event dispatched from an element inside your shadow root with only bubbles: true never reaches the page. Dispatch it from the host (this.dispatchEvent(...)), or add composed: true.

Dispatch from the host

The cleanest design is to dispatch public events from the host element itself. Then they work whether or not the host uses shadow DOM, and no composed flag is needed, because the host lives in the outer tree.

Two ways to get an event out

The first and third buttons reach the page (listening on document), while the second never does. The host-dispatched event needs only bubbles: true to reach document, because the host already sits in the outer tree. The inner events need composed: true as well.

bubbles and composed are separate switches. Crossing the boundary needs composed; travelling up through ancestors needs bubbles. A listener placed directly on the x-toggle element would hear via-host even without bubbles.

composedPath()

event.composedPath() returns the array of nodes the event passes through, from the innermost target outward. For an open shadow root it includes the internal nodes; for a closed root, the internals are hidden from outside listeners.

JavaScript
document.addEventListener("click", (e) => {
  console.log(e.composedPath().map((n) => n.localName ?? n.nodeName));
});

For an open x-box, the path would start with button, div, then a shadow root, then x-box, body, html, document and window. Use this for debugging or for analytics code that really does need to know the exact clicked element, and remember it is empty after the event has finished dispatching.

flowchart TB
  A["button (in shadow)"] --> B["div#wrap"]
  B --> C["#shadow-root"]
  C --> D["x-box (host)"]
  D --> E["body"]
  E --> F["document"]

The composed path of a click on an inner button. Outside listeners see the host, not the button.

Designing events for a boundary

  1. Public events come from the host. Keep them documented and stable.
  2. Do not leak internals. Put what outsiders need into detail instead of letting them read event.target.
  3. Re-dispatch native events deliberately. change from an inner <input> is not composed, so if your component should offer change, dispatch your own from the host.
  4. Stop what should not escape. If an internal event should not leave, call event.stopPropagation() at the boundary, or simply leave composed false.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does event.target equal for a listener outside a shadow root?

    Retargeting rewrites the target to the host so shadow internals stay hidden.
  2. 2. What happens to new CustomEvent('x', { bubbles: true }) dispatched inside a shadow root?

    Without composed: true, the event does not cross the shadow boundary, regardless of bubbles.
  3. 3. Which is the cleanest way to publish a public event?

    Events dispatched from the host live in the outer tree, so they need no composed flag and do not expose internals.
  4. 4. What does composedPath() give you?

    It is the event's propagation path, innermost first, and closed shadow trees are not exposed to outside listeners.

Summary

  • Retargeting rewrites event.target to the host outside the shadow tree.
  • Only composed events cross the boundary; custom events are not composed by default.
  • bubbles (up the ancestors) and composed (across the boundary) are independent.
  • Dispatch public events from the host and describe the details in detail.
  • composedPath() reveals the route for debugging.

Next: Form-Associated Custom Elements