Concepts
Anchors
Anchors are explicit ids on the elements guides point at. They survive redesigns that would break CSS selectors.
An anchor is an id you put on an element so a step can spotlight it.
| Platform | How |
|---|---|
| Web (script tag or npm) | <button data-guide="new-invoice-btn"> |
| React | <button {...guideAnchor('new-invoice-btn')}> |
| Flutter | GuideAnchor(id: 'new-invoice-btn', child: …) |
Use lowercase words separated by dashes. Name the thing, not its position: new-invoice-btn, not top-right-button.
Why explicit ids
Tour tools that record CSS selectors break when a class name or layout changes. An anchor is part of your code, reviewed like any other attribute, so guides keep working through redesigns. The same anchor id can exist on web and Flutter, so one guide runs on both.
How the SDK finds them
On the web the SDK watches the page for data-guide attributes, including elements added later by your framework. It spotlights the first visible match, follows it as the page scrolls or resizes, and waits a few seconds for elements that appear after navigation.
Without data-guide
Guides made with Generate with AI can point at elements your app never marked. Such a step keeps an anchor id and adds where to find the element:
| Platform | Found by |
|---|---|
| Web | A CSS selector that matched only that element when it was captured, plus its text when the selector alone is not enough |
| Flutter | The widget's ValueKey, its text, its semantics label or its tooltip |
An element with the same data-guide (or a GuideAnchor with the same id) always wins over the selector, so you can make any step robust later by adding the attribute. Edit a step's selector in the builder under Find it without data-guide. Selectors break more easily than anchors when your app changes; the stale-anchor alerts below tell you when one stops matching.
Guides with selector steps are published as guide spec version 2. An SDK that predates selector steps skips them instead of waiting for an element it cannot find.
Stale anchors
The SDK reports when it saw each anchor and when a step's anchor was missing. In Guides › Anchors an anchor used by a live guide is marked stale when it was reported missing after it was last seen, or has not been seen for 7 days. You also get an inbox alert, so you hear about it before your users do.