CSS Selectors

What's a CSS selector?

A CSS selector is a way to describe the location of one or more elements in an HTML page. It uses characteristics, such as IDs, classes and other attributes, to create a breadcrumb trail to a certain element(s) in the HTML tree. For a deeper dive on CSS selectors, check out  How CSS Selectors Work.

How does Appcues use CSS selectors?

When you initially place a tooltip or hotspot in our editor, we create a CSS selector for the element you are trying to annotate. We save the CSS selectors for each of those annotations so we can place them again later. You can think of CSS selectors as repeatable instructions for where your hotspots/tooltips/coach marks should go on the page.

When Appcues displays a tooltip or hotspot, it starts by scanning the page to locate the right elements to attach to (using the CSS selectors from the step mentioned above). As it does this, Appcues keeps track of which elements are present or absent from the page.

In some cases, Appcues requires that all elements are present on the page in order to start the tour. In other cases, a partial showing is ok. Any time an element is not present when we believe it should be, Appcues sends that information to our servers and shows that to you in our analytics. If an element is missing too often, we'll bring that to your attention.

Why would I need to change a CSS selector in Appcues?

The CSS selectors we create are a set of directions to an element on the page. That means a tooltip or hotspot can become irrelevant and not show if:

  • The element is no longer on the page.
  • The element has not displayed yet on the page
  • There are too many similar elements on the page, so we cannot find the original / unique element.

Things to consider when adding annotations

Keeping in mind the above constraints, we recommend these tips:

  • Only put annotations on elements that are available for all the users you are targeting. For instance, if there is a button that only shows up for paid users, flows that point out that particular button should only be targeted to paid users.
  • Ensure that elements you are attaching hotspots and tooltips to are consistently visible when the page has loaded.

For a deeper dive into the problem and solutions, read our doc on  Faulty CSS Selectors.