Events that Cross Shadow DOM Boundary

JS.info ⟩ Custom events in shadow DOM
Google ⟩ The Shadow DOM event model

The events that do cross the shadow boundary are:

Built-in Events

Most (built-in) events successfully bubble through a shadow DOM boundary (with event.composed == true).

There are few events that do not:

mouseenter, mouseleave (they do not bubble at all),
load, unload, abort, error
select
slotchange

These events can be caught only on elements within the same DOM, where the event target resides.

Custom Events

如果要讓 CustomEvent 跨過 shadow DOM boundary，必須要設定： {bubbles: true, composed: true} ⭐️

If composed: false (default), consumers won't be able to listen for the event outside of your shadow root.

// attach shadow root (⭐️ so outer's light DOM is not shown)
outer.attachShadow({mode: 'open'});

let inner = document.createElement('div');
outer.shadowRoot.append(inner);

/*
div#outer
  #shadow-dom
    div#inner
*/

// ⭐️ listen for 'test' event
document.addEventListener('test', e => log(lightDOM, e.detail));
outer.shadowRoot.addEventListener('test', e => log(shadowDOM, e.detail));

// ⭐️ composed custom event
function sendComposedEvent(){
  inner.dispatchEvent(new CustomEvent('test', {
    bubbles: true,
    composed: true,       // ⭐️ composed
    detail: "'composed' event from inner <div>"
  }));
}

// ⭐️ not composed custom event
function sendNonComposedEvent(){
  inner.dispatchEvent(new CustomEvent('test', {
    bubbles: true,
    composed: false,       // ⭐️ not composed
    detail: "not composed"
  }));
}

// ⭐️ escape HTML special characters
String.prototype.escapeHTML = function () {
    return this 
        .replace(/&/g, '&amp;' )    // ampersand (must be first❗️)
        .replace(/>/g, '&gt;'  )    // greater than
        .replace(/</g, '&lt;'  )    // less than
        .replace(/"/g, '&quot;')    // double-quote
        .replace(/'/g, '&#39;' )    // single-quote
        .replace(/`/g, '&#96;' );   // backtick
}

// log
function log(dom, msg) {
  dom.innerHTML += msg.escapeHTML() + '<br>';
}

<!-- ⭐️ element with shadow DOM -->
<div id="outer">outer div</div>

<div id="buttons">
  <button onclick="sendComposedEvent()">composed event</button>
  <button onclick="sendNonComposedEvent()">non-composed event</button>
</div>

<!-- console log -->
<div id="lightDOM" class="output">
  <p>Light DOM event logs:</p>
</div>

<div id="shadowDOM" class="output">
  <p>Shadow DOM event logs:</p>
</div>

.output {
  border: 1px solid black;
  padding: 8px;
  background: black;
  color: white;
}

.output p {
  margin: -8px;
  margin-bottom: 8px;
  padding: 8px;
  background: tomato;
}

#lightDOM p {
  background: hsl(225, 80%, 60%);
}

#buttons {
  margin-bottom: 8px;
}

In case of nested components, one shadow DOM may be nested into another. In that case composed events bubble through all shadow DOM boundaries. So, if an event is intended only for the immediate enclosing component, we can:

dispatch it on the shadow host
set composed: false.

Then it’s out of the component shadow DOM, but won’t bubble up to higher-level DOM.

PreviousActive Element NextBubbling in Shadow DOM

Last updated 4 years ago

Was this helpful?