Shadow DOM

In our new SDK release, we've implemented autocapture for change, submit, and click events within Shadow DOM. When the shadow root is set to "open", we capture all three event types. However, when the shadow root is set to "closed," we only capture click events propagated to the regular DOM host element. These events will register against the shadow host even if these events originate deep within the shadow tree.


Functionality Notice

At the moment, the Visual Labeler does not support Shadow DOM. We recommend using Live View instead.

What is Shadow DOM?

The fundamental role of Shadow DOM is to enable the encapsulation and isolation of DOM structures. This isolation ensures that these structures can be utilized in various contexts without being influenced by the behavior outside of the Shadow DOM. Shadow DOM allows hidden DOM trees to be attached to elements in the regular DOM tree. This hidden tree begins with a shadow root, where you can attach additional elements just like you would in the regular DOM.

A Shadow DOM can be open or closed. Setting the Shadow DOM to 'open' allows you to interact with it using JavaScript code written in the context of the main page. With a closed Shadow DOM, you won't be able to access it from the outside (host.shadowRoot will return null).

Event Propagation Within Shadow DOM

Event propagation describes how events are dispatched, captured, and processed by elements in the DOM. When DOM events are constructed, whether custom or built-in, they contain 2 boolean properties, among others, that dictate how that event will propagate.

  • bubbles - refers to the process where an event travels up the DOM tree from the target element to its ancestors
  • composed - determines whether the event can cross shadow DOM boundary

If composed is set to true, the event will propagate through the shadow tree hierarchy outside the shadow boundary regardless of whether it is bubbling or not. If bubbles is set to true events propagate through the parent-child hierarchy. Most standard UI Events, including click, bubble and are composed.


Shadow DOM Terminology

  • Shadow Host: A non-Shadow DOM node that a given Shadow DOM is attached to.
  • Shadow Tree: The Shadow DOM tree.
  • Shadow Boundary: The boundary where the Shadow DOM ends and the regular DOM begins.
  • Shadow Root: The root node of the Shadow DOM.
  • Shadow Element: An element that lives within a Shadow DOM