Using CSS selectors in Feature tagging

Pendo uses CSS selectors in tagging rules for creating Features. These rules identify specific elements within your application that you want to pull into a named Feature in Pendo when visitors interact with these elements. This article summarizes supported CSS selectors and how to deal with dynamic CSS selectors. For more information about tagging Features in Pendo, see Feature tagging.

Tagging Features using CSS selectors

When tagging a Feature, Pendo suggests a CSS selector for you under Suggested Match. If you want to choose an alternative CSS selector, you can instead use the Rule Builder for guided rule creation based on your application's code, or the Custom CSS option for full control over the creation of the CSS selectors in your rules.

For example, the following rule specifically targets a button with the text "Next" in it: button:contains('Next'). For more examples of the syntax used in CSS selectors, see W3Schools' CSS Selectors Reference.

Supported syntax

• .class
• #id
• element
• element element
• element,element
• element > element
• [attribute]. We support "href" and "value".
• [attribute="value"]. See Syntax limitations, below.
• [attribute*="value"]
• :nth-child(index). Index is 1-based.
• :contains("text"). The text in the selector must match the text in your HTML exactly. See also Syntax limitations, below.
• ^=
• $=

Syntax limitations

The following limitation apply to syntax for Feature tagging.

• Siblings elements are unsupported.
• When using the [attribute="value"] selector, only certain attributes are allowed. For more information, see HTML attributes in data collection.
• Not all types of element are supported. You can't use option. For more information, see the following troubleshooting article: No click events for tagged dropdown menu item.
• If you're using nested element, such as a class inside of another class, you can't use more than one contains rule in a Feature tag.
• If you're using multiple rules, you can only use contains with the last rule for the Feature. For example, the following won't work because :contains isn't part of the last rule in the set: .rule:contains("stuff") .another-rule.

Dealing with dynamic CSS selectors

Typically, you should look for the most specific CSS selector for the UI element you’re trying to tag. If the HTML attribute you’re trying to use is dynamic, you must find a balance between specificity and flexibility to capture only the part of the CSS selector that remains consistent.

Many websites rely on dynamically generated CSS selectors. Because CSS selectors affect how you tag Features and target guides, it’s important to ensure that the CSS selector you’re tagging is a stable identifier that’s unlikely to change over time. 

A dynamic CSS selector is typically a Class name or element ID that’s likely to change due to activity in the application, such as a text heading that changes color when a user passes a mouse over it, or a new version of the application.

You can identify dynamic CSS selectors by looking for a seemingly random string of characters in the CSS selector. When you find dynamic CSS selectors, you can instead:

• Tag Features in Pendo using rules starts-with (^), ends-with ($), and contains (*) rule to ignore the dynamic parts of the CSS selector. This ensures Pendo is only matching to the part of the attribute that’s consistent. For more information, see Advanced Feature Tagging.
• Add static Classes and IDs to elements in your application to make your code more stable for Feature tagging and guide targeting.
• Use custom HTML elements to provide static selectors for use by Pendo.

Nth-child rule considerations

Nth-child() rules specify an element based on the structure of the page. If the structure changes, the rule might no longer target the intended element. For instance, if an element that was the third child becomes the fourth child after a product change, the nth-child rule will no longer match the correct element.

Nth-child() rules can be effective for specifying elements based on their position within a parent element, particularly in simpler applications where the structure is unlikely to change frequently. They can also be useful as placeholders to identify elements if you plan to add a more specific attribute later.

If you choose to use nth-child() as your Feature rule, we recommend regularly reviewing and updating these rules to ensure they still accurately target the desired elements, especially if your application is updated frequently.

Where possible, use custom HTML attributes or more stable identifiers to ensure consistency in your Feature tagging. While nth-child() rules can be a helpful starting point, we recommend implementing more robust solutions for long-term stability.

Additional resources