CSS Selectors

For a deeper dive into the problem and solutions, check out Manually Build CSS Selectors below.

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:
  • 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 a 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.

Hotspots or tooltips may not appear if our SDK cannot identify the specific elements which the hotspots or tooltips are set to attach to.  

When an element does not appear, this usually happens for three reasons:

Missing elements

If you place a tooltip or hotspot on an element that doesn't exist in all instances, your flows will not show up when those elements don't appear.

For example, in the image below we have a tooltip placed on Project 2. If a user doesn't have two projects, the tooltip would not appear on this page as it would be seeking a CSS selector for the second project.

Auto-generated selectors

Sometimes your elements will be visible in all instances, but they might have auto-generated attributes (classes, IDs, etc). In this case, elements in your HTML markup will look like this: 

Auto-generated attributes (like "core___2PzPF" above are common in certain javascript frameworks like React.js and Ember.js. These IDs are randomly generated on each page load. As such, Appcues won't be able to automatically determine the best CSS selector to use when building your Appcues hotspots or tooltips.

In order to get your tooltips/hotspots to display properly, remove the auto-generated portion of the CSS selector.


In the Appcues editor, click on the cog icon next to the tooltip or hotspot you would like to adjust:

You will now see the auto-generated CSS selector being used to position your step. Here are instructions on other methods of representing an attribute. For instance, if you had the following CSS selector

div.menu-panel__2Hkc9 > header

You could replace the auto-generated portion by adjusting it to:

div[class^=menu-panel__] > header

Alternatively, you can build your own selector from other attributes associated with the targeted element.  The Appcues editor will gather and list out the following attributes when available: HTML tag type, id, class, href, src, alt, title, type, name, and placeholder:

Generic CSS selectors

If CSS selectors are too general and can be referred to more than one element on your page, tooltips or hotspots cannot identify which element to appear on and therefore will not show: 

To get your flows appearing on the correct elements, identify a more unique selector by inspecting the element on your page. Once you have a more specific selector, click on the cog icon of the hotspot or tooltip you would like to adjust and then add the unique identifier in the Selector field, or select another attribute in the list: 

You can also select By Order if you have multiple objects with the same CSS header!

Messaging in the Element Selector will alert you that your selector, whether inputted automatically or manually, is 1) unique and valid, 2) valid, but not unique, or 3) not found. Choose a selector that is both unique and valid.  Save your new selector and preview your flow to make sure it works.

Selectors that change on empty state

Another thing to keep in mind is that a selector may be slightly different when someone looks at a part of your page in its empty state (vs with it populated). So be sure to run through the flow with a clean slate as a new user would and ensure that the selector is the same in both states. Usually, we find that in this case, there is some part of the selector that is consistent.


Still stuck?

Please reach out to support@appcues if you have questions on the above. =)