Anchor tour steps to UI elements

Pointer tooltip steps and pointer-with-video steps need to know which element on the page to point at. You give Yaplet that information as a CSS selector. This article explains how to write a reliable selector, how Yaplet handles missing elements, and how to update selectors when your UI changes.

How to find the right CSS selector

The easiest way is to use your browser's developer tools:

1. Open the page where the element lives in your browser.
2. Right-click the element and choose Inspect (or press F12 and click the element picker).
3. In the Elements panel, right-click the highlighted node and choose Copy → Copy selector.
4. Paste the selector into the step's Element selector field in the tour builder.

Browser-generated selectors often include :nth-child() indices that break when the DOM order changes. Simplify them when possible (see below).

Writing a resilient selector

The best selectors are ones that identify an element by what it is, not where it is in the DOM. Ranked from most to least resilient:

1. Data attribute — [data-tour="new-project-button"]. Add a data-tour attribute specifically for tour anchors. This is the most stable option because it never changes unless you change it deliberately.
2. Unique ID — #create-project-btn. Reliable if your IDs are stable and not auto-generated.
3. ARIA label or role — [aria-label="Create project"]. Good if your components use consistent accessible labels.
4. Class name — .create-project-button. Acceptable for design-system components with stable class names. Avoid utility classes like .flex or .mt-4 — they match dozens of elements.
5. Structural selector — header nav ul li:first-child a. Fragile — breaks whenever the DOM structure changes.

What happens if the element isn't found

If Yaplet can't find the selector on the page when the tour step activates:

• The step falls back to a centered modal position — the tooltip appears in the centre of the screen with no arrow.
• The tour continues normally from the next step.

This means a broken selector degrades gracefully rather than crashing the tour. But the step will look wrong, so monitor your tour analytics and update selectors promptly after UI changes.

Handling dynamic elements

Some UI elements appear only after an interaction — a dropdown that opens after a click, a panel that loads after navigation. For these:

• Use a Link step before the pointer step to navigate to the right page and give the UI time to settle.
• Add a delay to the trigger in seconds so the step fires after any animations complete.
• If the element is lazy-loaded, consider a data attribute that's added to the DOM as soon as the container renders, even before the lazy load finishes.

Updating selectors after a UI change

When you ship a UI update that moves or renames elements:

1. Open the affected tour in the dashboard.
2. Click through each step that targets a modified element.
3. Update the CSS selector to match the new markup.
4. Use the Preview button to verify the arrow points to the right element before saving.

What's next?

Once your steps are anchored correctly, make sure the tour looks good on smaller screens: Make a tour responsive across breakpoints.