Skip to main content

Guide Display Issues

My Guide Isn't Showing​

Mutation Observer & Shadow DOM Limitation​

The Problem

Guide does not display when it's target element becomes visible and your application uses Web Components or frameworks with Shadow DOM elements (such as Polymer or Lit)

Applications created after June 2023 spin up with the preferMutationObserver application flag enabled. Instead of evaluating a page every 500ms for guide eligibility, this setting makes the agent responsive to changes in the document. In most cases, this will yield better performance since the agent will spend less time processing on the main thread.

However, a limitation of the MutationObserver API is that it does not detect changes in elements encapsulated in Shadow DOM trees. To remedy this, we have an additional config setting observeShadowRoots that’s available when preferMutationObserver is enabled. As part of the agent’s startup, we run a full document scan for shadow root elements and attach MutationObservers to each instance. The observeShadowRoots setting is disabled by default, since the scan and additional observers may add unnecessary overhead.

The Fix

To get the guide to reshow, try enabling the observeShadowRoots flag or disabling preferMutationObserver. Both options should result in the guide showing when the target element becomes visible. These settings can be configured from the App Details page or passed as boolean values to pendo.initialize()

Settings → Subscription Settings → View App Details:

  • “Prefer MutationObserver to 500ms timer, when available” checkbox for preferMutationObserver
  • “Use MutationObserver on Shadow DOM elements” checkbox for observeShadowRoots (only present in the UI when preferMutationObserver is enabled)