Anchor tour steps to UI elements

Updated May 22, 2026

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 (the builder calls them Fallback selectors). 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 (the builder calls them Fallback steps): 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 Skip if hidden in the builder (the flow list shows Skipped if hidden), the tour jumps straight to the next step.
  5. If the element is not on the page at all, Yaplet keeps looking for it for a few seconds, a little longer 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.

Picking an element

You do not type a selector. In the tour builder, add a pointer step, click the crosshair button at the top of the step editor (it reads Click to select element), then click the element on your page. Yaplet writes the selector for you and shows it on that button. To add a backup, click Add selector under Fallback selectors and click another element — for example the phone version of a menu.

The selector is built from what the element has in your page: a unique id if there is one, otherwise its class names, and only as a last resort its tag and position. Selectors that rely on position are brittle — they break the moment anything moves — so pick elements that can be described by what they are, not where they sit.

Choosing an element that lasts

Good anchors describe what an element is, not where it is. Give the elements your tours point at something stable in your own markup. Best first:

  1. A unique id — #create-project-btn. Yaplet uses it first. Reliable, as long as your ids are not generated fresh on each build.
  2. A dedicated class name — .create-project-button. Fine for a design system, and easy to add to your own markup purely for tours. Avoid utility classes such as .flex; they match dozens of elements.
  3. A structural path — header > nav > ul > li:nth-child(1) > a. This is what Yaplet falls back to when the element has no id or class. 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: click Navigate in the builder, go to that page and add the step there, so the tour moves there first.
  • Add extra selectors (Add selector under Fallback selectors) covering the alternative shapes the interface can be in.
  • Do not add a fallback step that points at nothing (a fallback post) 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, click Edit flow, then Start tour builder to reopen the builder on your live site.
  2. Walk through the steps that touch changed screens and re-point them.
  3. Press Save in the builder, then click Save changes 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.

Did this article answer your question?