You can attach guides to specific elements on a page in your web application. Pendo uses CSS selectors to attach guides to elements on a web application page.
This article provides guidance for using CSS selectors to target guides to elements in your web application, which is relevant to both install script and browser extension implementations of Pendo.
CSS rules are also used for Feature tagging, but don't have the same performance considerations. For more information about CSS rules for Feature tagging, Using CSS selectors in Feature tagging.
Guide targeting with CSS
Ensure that your CSS selector is correctly identifying the intended element on your page:
- Preview your guide to confirm that it displays in the desired position.
- Check that you aren't getting any warnings about multiple element matches or unstable selectors. A selector might evaluate quickly but still return unexpected results, leading to inconsistent guide display results.
CSS selector speed
After building a guide that successfully attaches to a target element, consider the speed of the selector. CSS selectors are evaluated frequently in your application to determine when and where to show the guide. Too many slow selectors can cause guide display issues or performance problems within your application.
The color-coded CSS strength bars underneath your selection in the Visual Design Studio provides real-time feedback on the speed of your selectors. Aim to have each CSS selector validated with three bars in the green for the smallest impact on your application performance. CSS selectors with three strength bars that are color-coded as green require less than 5 ms processing time. With this processing time for CSS selectors, Pendo can manage many guides without a noticeable impact on your application’s performance.
If you find that your guides are consistently failing to display or if your application seems slower due to Pendo’s presence on the page, the speed of your selectors might be the cause.
Improving CSS selector speed
CSS selectors are generally fast. However, some types of selectors can take longer for Pendo to process, such as those that use the :contains rule, custom HTML attribute selectors, and elements in shadow roots. Additionally, as page size increases, the time it takes to evaluate these selectors can scale accordingly.
There are several ways to improve these CSS selectors for more efficient DOM queries. The reason these selectors can be slow is that they might need to evaluate the entire page to find matches. If you increase the specificity of the selector, you can avoid some of that processing.
From a Pendo performance standpoint, consider the CSS selector efficiency hierarchy below:
- IDs, for example,
#nav
- Classes, for example,
.button
- Tag names, for example,
div
- Element combinators, for example,
div span
or.header > .button
- Elements in shadow roots, for example,
div::shadow li
- Custom HTML attributes, for example,
[data-value=100
- Contains rules, for example,
div:contains("Welcome")
To improve the performance of your CSS selector, try using selectors higher in this hierarchy. Being more specific with your CSS selectors can help bypass unnecessary page calculations for locating your target element.
Example
For example, if your current CSS selector rule for a badge is a:contains("New feature")
and is currently red in the performance bar, evaluate the hierarchy to see whether there is an element or higher up in the hierarchy that you can use.
In this example, you might have used this selector because this <a>
element has a dynamic class that changes frequently. In this case, the element is always a link tag inside of an unordered list <ul>
, and you can change your selector to ul a:contains("New feature")
. After this change, the selector's performance improves and moves the strength indicator into yellow.
Instead of matching the text across every element on the page, you are now only evaluating the <a>
tags that are within a <ul>
tag. This is better, but you can also do more to improve the speed of the CSS selector.
If, for example, this specific element is located in the navigation bar, you can instead choose a CSS selector based on the ancestor element with a fixed class name: .nav-bar a:contains("New feature")
which increases the performance of the CSS selector into the green.
By using the performance bar in the Visual Design Studio, you can experiment with selector combinations to build the most efficient rule for your page. You don’t need to entirely avoid the slower selector types. Combining slower selection types with faster selectors can greatly improve page performance.