This article explains how to tag Features that exist in a shadow DOM. A shadow DOM is a specialized structure in web applications that can affect how Pendo detects and matches elements.
Understanding how to work with shadow DOMs helps ensure your tags remain accurate and reusable.
Prerequisites
To tag Features inside a shadow DOM:
- Your application must use shadow DOM elements in "open" mode.
- Your Pendo Web SDK version must be 2.38.0 or above.
- You must use a browser that supports inspecting shadow DOMs with developer tools, such as Google Chrome.
Note: Pendo doesn’t support shadow DOMs in closed mode.
About shadow DOM
The DOM (Document Object Model) is a hierarchical tree structure representing all the elements on a web page. Each element in the page (for example, divs, forms, buttons) appears as a node in the DOM tree. When you tag a Feature in Pendo, you're telling Pendo where to find that element in the DOM structure.
A shadow DOM is a specialized subtree within the DOM that's isolated from the rest of the document. It’s often used to encapsulate the styles and behavior of reusable components (such as modals or dropdowns). Shadow DOMs improve performance by limiting what needs to be reprocessed when changes occur.
A shadow DOM acts as a mini-DOM inside the main DOM. It’s isolated and must be explicitly accessed using the correct syntax.
Below is a diagram outlining the DOM structure of a fake webpage with a shadow DOM. The left side contains the different classes and IDs that make up a submit button on a chart. The right side shows inside a shadow DOM the classes and IDs that make up an export button on a table.
Tip: For more information, see MDN's article on Using shadow DOM.
Why shadow DOMs are important for tagging
Because Feature tagging works by identifying elements in the DOM, elements inside a shadow DOM require different syntax. If you try to tag a shadow DOM element using a standard selector, it won’t match.
For example:
-
Regular selector:
.container .chart #submit-button -
Shadow DOM selector:
.container::shadow .table #export-button
The ::shadow part tells Pendo to enter a shadow DOM boundary when locating elements.
How to tell if an app uses a shadow DOM
There are two main ways to determine whether a Feature is inside a shadow DOM:
Review the suggested tagging rule
In the Visual Design Studio, select an element and look at the suggested match rule. If you see ::shadow in the rule, that means the element is inside a shadow DOM.
Inspect the page in Chrome
- Right-click the element and choose Inspect to open Chrome DevTools.
- Select the gear icon in the top-right to open Settings.
- Under Preferences > Elements, check Show user agent shadow DOM.
- In the Elements panel, look for elements nested under
#shadow-root (open)in the hierarchy.
Tag elements in a shadow DOM
When tagging a Feature in a shadow DOM, we recommend starting with the suggested Feature match rule that Pendo provides in terms of its structure. However, the Feature tag may be more specific than you want (for example, it refers to an individual instance of a feature within the shadow DOM instead of a group of like features).
In these instances, you should edit the too-specific rule while leaving the references to the shadow elements of the DOM intact. For example, in the image below, we see the DOM tree for a page with a table and two buttons, an import and an export button.
Here's another example for tagging a single button, where the suggested rule is:
.container::shadow .table #export-button
And the updated rule to match all buttons is:
.container::shadow .table .button
It's important to keep the ::shadow parts intact and only adjust the most specific part of the selector to broaden or refine the match.
Tag nested shadow DOMs
If the application includes shadow DOMs within other shadow DOMs, you must include each layer in your match rule using ::shadow multiple times.
See an example in the following image:
Here's another example for tagging through two layers of shadow DOM:
.container::shadow .report::shadow .table #export-button
In this example, .report is inside the first shadow DOM, and .table and #export-button are inside a second nested shadow DOM.
Validate your rule using the browser console
You can test any match rule in your browser console to confirm that it targets the correct element.
To confirm your rule works as expected:
- Right-click the page and choose Inspect to open Chrome DevTools.
- Open the Console tab.
- If you're using a browser extension installation, change the context to Pendo Launcher using the dropdown menu at the top of the console.
- Run the following command:
pendo.dom(`.container::shadow .table .button`)- Expand the results and hover over each entry to verify that the correct elements are highlighted.
Tip: This method works for any Pendo match rule, not just shadow DOM selectors.