Event.composed
The read-only composed
property of the
Event
interface returns a Boolean
which indicates whether
or not the event will propagate across the shadow DOM boundary into the standard DOM.
Note: This property was formerly named scoped
.
Syntax
const isComposed = Event.composed;
Value
A Boolean
which is true
if the event will cross from the
shadow DOM into the standard DOM after reaching the shadow root. (That is, the first
node in the shadow DOM in which the event began to propagate.)
All UA-dispatched UI events are composed (click/touch/mouseover/copy/paste, etc.). Most
other types of events are not composed, and so will return false
. For
example, this includes synthetic events that are created without their
composed
option set to true
.
Propagation only occurs if the bubbles
property is also
true
. However, capturing only composed events are also handled at host as
if they were in AT_TARGET
phase. You can determine the path the event will
follow through the shadow root to the DOM root by calling
composedPath()
.
If this value is false
, the shadow root will be the last node to be
offered the event.
Examples
In our composed-composed-path example (see it live), we define two trivial custom
elements, <open-shadow>
and <closed-shadow>
, both
of which take the contents of their text attribute and insert them into the element's
shadow DOM as the text content of a <p>
element. The only difference
between the two is that their shadow roots are attached with their modes set to
open
and closed
respectively.
The first definition looks like this, for example:
customElements.define('open-shadow',
class extends HTMLElement {
constructor() {
super();
let pElem = document.createElement('p');
pElem.textContent = this.getAttribute('text');
let shadowRoot = this.attachShadow({mode: 'open'})
.appendChild(pElem);
}
});
We then insert one of each element into our page:
<open-shadow text="I have an open shadow root"></open-shadow>
<closed-shadow text="I have a closed shadow root"></closed-shadow>
Then include a click event listener on the <html>
element:
document.querySelector('html').addEventListener('click',function(e) {
console.log(e.composed);
console.log(e.composedPath());
});
When you click on the <open-shadow>
element and then the
<closed-shadow>
element, you'll notice two things.
- The
composed
property returnstrue
because theclick
event is always able to propagate across shadow boundaries. - You'll notice a difference in the value of
composedPath
for the two elements.
The <open-shadow>
element's composed path is this:
Array [ p, ShadowRoot, open-shadow, body, html, HTMLDocument https://mdn.github.io/web-components-examples/composed-composed-path/, Window ]
Whereas the <closed-shadow>
element's composed path is a follows:
Array [ closed-shadow, body, html, HTMLDocument https://mdn.github.io/web-components-examples/composed-composed-path/, Window ]
In the second case, the event listeners only propagate as far as the
<closed-shadow>
element itself, but not to the nodes inside the
shadow boundary.
Specifications
Specification | Status | Comment |
---|---|---|
DOM The definition of 'composed' in that specification. |
Living Standard |
Browser compatibility
BCD tables only load in the browser