You can attach guides to specific elements in your web application using CSS selectors. Choosing the right selector helps ensure your guides display reliably and don't affect your application's performance.
Choose an element
When you create or edit a guide, you can choose the element that controls when the guide launches in your application. To choose an element:
- From the left-side menu, go to Guides > Guides.
- Select the guide you want to edit.
- Select Edit in my app to open the Visual Design Studio. The guide opens over your application and the Edit container window appears.
- Select the Location tab.
- In the Anchor to Element section, choose the element option that best identifies where your guide should appear.
Anchor element options
The Anchor to Element section gives you three options for identifying the element that launches your guide. Each option produces a CSS selector that controls where your guide appears.
- Suggested Match: This automatically generates the most stable CSS selector it can find for the element you selected. This option works for most guide targeting scenarios.
- Parent Element: Uses the parent element's CSS selector instead of the selected element itself. This is useful when the selected element has an unstable or dynamically generated selector.
- Custom CSS: Lets you manually enter any CSS selector, giving you full control when the automatic options don't reliably identify the right element. The Tagging Aid Chrome Extension can help you find a selector that works for your use case. For more information about using the Tagging Aid, see Pendo Tagging Aid.
Troubleshooting
If your guide isn't displaying as expected, check both your selector accuracy and its performance. Either can cause inconsistent or failed guide display.
Check your selector
Before considering performance, confirm that your selector is working as expected:
- Preview your guide to verify it displays in the correct position.
- Check for warnings about multiple element matches or unstable selectors. A selector can evaluate quickly but still return unexpected results, which leads to inconsistent guide display.
CSS selector performance
Because selectors are evaluated frequently, slow selectors can cause guides to display inconsistently or affect your application's performance. The color-coded CSS strength bars in the Visual Design Studio provide real-time feedback on selector performance.
Aim for three bars in the green for each selector. Green selectors require less than 5 milliseconds to process, which allows the platform to manage many guides without a noticeable impact on your application.
If you find that your guides are consistently failing to display or if your application seems slower due to the guides, the performance of your selectors might be the cause.
Improving CSS selector performance
Some selector types take longer to process than others. Selectors that use :contains rules, custom HTML attribute selectors, and elements in shadow roots are slower. As page size increases, the time it takes to evaluate these selectors increases as well.
To improve performance, increase the specificity of your selector. The following hierarchy shows selector types from fastest to slowest:
- IDs, such as
#nav - Classes, such as
.button - Tag names, such as
div - Element combinators, such as
div spanor.header > .button - Elements in shadow roots, such as
div::shadow li - Custom HTML attributes, such as
[data-value=100 - Contains rules, such as
div:contains("Welcome")
Use selectors higher in this hierarchy where possible. You don't need to avoid slower selector types entirely. Instead, combining a slower type with a faster one can significantly improve performance.
Example: Improving a slow selector
Your current selector is a:contains("New feature") and the strength bar shows red.
Because the <a> element has a dynamic class that changes frequently, you used a :contains rule instead. However, the element always appears inside an unordered list <ul>, so you can update the selector to ul a:contains("New feature"). This narrows the match to <a> tags within <ul> tags rather than searching the entire page, which moves the strength indicator to yellow.
If this element is in the navigation bar, you can choose a CSS selector based on the ancestor element with a fixed class name: .nav-bar a:contains("New feature"). This moves the strength indicator to 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.