JavaScript Event composed Property

What You’ll Learn

The composed property is a read-only boolean on every Event: true if the event can cross the shadow DOM boundary into the light DOM, false if the shadow root is the last stop. Learn how it pairs with bubbles, how to set it on synthetic events, and how composedPath() reveals the path—with five examples and try-it labs.

Introduction

Web Components hide markup inside a shadow tree. Some events that start inside that tree should still reach listeners on the page outside—others should stay private. event.composed is the flag that answers that question.

Browser UI events such as click are composed, so a click inside a custom element can still be heard on document. Most custom synthetic events are not composed unless you pass { composed: true } to new Event().

Understanding Event.composed

An instance property that answers: “After this event reaches the shadow root, may it continue into the standard DOM?”

• Value — true if it can cross; false if the shadow root is the last node.
• Read-only — set only at construction for synthetic events.
• UI events — browser click / touch / mouseover / copy / paste (and similar) are composed.
• With bubbles — bubble-phase travel across the boundary needs bubbles too.
• Baseline Widely available on MDN (since January 2020); also in Web Workers.

📝 Syntax

event.composed

Value

A boolean: true if the event will cross from the shadow DOM into the standard DOM after reaching the shadow root.

Set on synthetic events

const privateEvt = new Event("notify"); // composed: false (default)
const publicEvt = new Event("notify", { bubbles: true, composed: true });

console.log(privateEvt.composed); // false
console.log(publicEvt.composed);  // true

See the path

document.addEventListener("click", (e) => {
  console.log(e.composed);
  console.log(e.composedPath());
});

⚖️ composed vs Related Ideas

🎨 Open vs Closed Shadow Roots

MDN’s classic demo defines custom elements with mode: "open" and mode: "closed". Clicks are always composed === true, but composedPath() differs:

• Open — path can include inner nodes (for example a p inside the shadow root).
• Closed — outer listeners often see the host element, not the private inner nodes.

That protects encapsulation while still letting composed UI events reach the page.

Examples Gallery

Examples follow MDN Event: composed. Use View Output or Try It Yourself.

document.getElementById("btn").addEventListener("click", (event) => {
  console.log("composed =", event.composed); // true for click
});

composed = true

const a = new Event("notify"); // default composed: false
const b = new Event("notify", { composed: true });

console.log(a.composed); // false
console.log(b.composed); // true

false
true

document.querySelector("html").addEventListener("click", (e) => {
  console.log("composed =", e.composed);
  console.log(
    e.composedPath().map((n) => n.nodeName || n.toString()).join(" → ")
  );
});

composed = true
BUTTON → DIV → BODY → HTML → [object HTMLDocument] → [object Window]

const host = document.getElementById("host");
const root = host.attachShadow({ mode: "open" });
const inner = document.createElement("button");
inner.textContent = "Inside shadow";
root.appendChild(inner);

document.body.addEventListener("notify", () => {
  console.log("body heard notify");
});

// Stays in shadow (not composed):
inner.dispatchEvent(new Event("notify", { bubbles: true }));

// Leaves shadow:
inner.dispatchEvent(
  new Event("notify", { bubbles: true, composed: true })
);

body heard notify
(only after the composed:true dispatch)

// After defining  and  like MDN:
document.querySelector("html").addEventListener("click", (e) => {
  console.log(e.composed); // true for click
  console.log(e.composedPath());
  // Open: may include inner 
, ShadowRoot, host, ...
  // Closed: often starts at the host, without inner nodes
});

composed = true for both
Open path includes inner nodes; closed path hides them

🚀 Common Use Cases

• Custom element events that the page (or a parent) must hear.
• Keeping internal component signals private (composed: false).
• Debugging event paths with composedPath().
• Understanding why a click escapes shadow DOM but a custom event does not.
• Designing APIs for design systems built on Web Components.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since January 2020) — no Deprecated / Experimental / Non-standard banner.
• Available in Web Workers.
• Read-only—set via constructor options for synthetic events.
• Bubble across shadow needs bubbles as well as composed.
• Related learning: bubbles, cancelable, Event(), addEventListener(), JavaScript hub.

💡 Best Practices