Anchor tour steps to UI elements

Your tour worked perfectly, then you shipped a redesign and now a step points at nothing. This article explains how a step finds its element, what Yaplet does when it cannot, and how to write anchors that survive your next release.

How a step finds its element

Each pointer step stores a selector — a short piece of text that describes an element on the page, the same language browsers use internally. A step can also store extra selectors as backups. Open a step in the tour's flow list and you will see the main one, with any extras listed under it.

What happens when the element is not there

Yaplet does not just give up. When a step opens, it works down this list until something succeeds:

1. It tries the main selector. If the element is on the page and visible, the tooltip anchors to it.
2. It tries each extra selector in turn and takes the first visible match.
3. It tries the step's fallbacks: alternative versions of the step, in order. A fallback that points at nothing is always usable, so it is taken immediately.
4. If the step is marked Skipped if hidden, the tour jumps straight to the next step.
5. If the element is not on the page at all, Yaplet keeps retrying for about two seconds — about five when the tour has just navigated to another page.
6. Otherwise, the step is shown in the middle of the screen with nothing highlighted.

The badges on a step in the flow list tell you which of these are set up: the count of extra selectors, the count of fallbacks, and a Skip badge.

The practical consequence: a broken selector never crashes a tour, but it does turn a helpful arrow into a floating card that explains something the visitor cannot see. Fix it, do not leave it.

Finding a selector

The quickest way is your browser's developer tools:

1. Open the page where the element lives.
2. Right-click the element and choose Inspect.
3. In the panel that opens, right-click the highlighted line and choose Copy → Copy selector.

What you get is usually correct but brittle — browsers write selectors that describe where an element sits, and those break the moment anything moves. Simplify it using the ranking below.

Writing an anchor that lasts

Good anchors describe what an element is, not where it is. Best first:

1. A dedicated attribute — [data-tour="new-project-button"]. Add it to your own markup purely for tours. Nothing changes it unless you do.
2. A unique id — #create-project-btn. Reliable, as long as your ids are not generated fresh on each build.
3. An accessible label — [aria-label="Create project"]. Good if your components label themselves consistently.
4. A class name — .create-project-button. Fine for a design system. Avoid utility classes such as .flex; they match dozens of elements.
5. A structural path — header nav ul li:first-child a. Works today, breaks tomorrow. Use only if there is nothing else.

Elements that appear late

Some elements only exist after something else happens — a menu opens, a panel finishes loading. Options, in order of preference:

• Put the step on the page where the element is already visible, using the step's own page address so the tour navigates there first.
• Add extra selectors covering the alternative shapes the interface can be in.
• Do not add a fallback that points at nothing just because an element is slow — Yaplet takes that fallback immediately instead of waiting, so the visitor gets the plain card even when the real element was about to appear. Keep empty fallbacks for elements that genuinely are not there.
• Add a delay to the trigger with After page view, so the tour starts once the page has settled.

After a redesign

1. Open the tour and click Edit flow to reopen the builder on your live site.
2. Walk through the steps that touch changed screens and re-point them.
3. Save in the builder, then click Save on the tour itself — the builder alone does not persist anything.

What's next?

Small screens are where anchors break most often. See Make a tour work on phones and tablets.