DocsWebsites
Choosing selectors
Point steps at the right elements with selectors that survive redesigns and rebuilds.
Every web step points at an element using a CSS selector — the same syntax as document.querySelector(). The first element that matches is the one the step highlights.
Best practice: add data-tour attributes
The most reliable selector is one you add on purpose. Put a data-tour attribute on each element a tour points at, then target that attribute:
<button data-tour="new-project">New project</button>
<nav data-tour="main-nav">…</nav>[data-tour="new-project"]Attributes like this survive redesigns, CSS refactors and framework upgrades. Auto-generated class names (css-1x2y3z, sc-bdVaJa, Tailwind utility soup) change between builds and will silently break your tour.
Tip
If you use an AI coding agent with our MCP server, it will add
data-tour attributes to your components for you before creating the tour.Selector cheatsheet
| Selector | Matches | Reliability |
|---|---|---|
[data-tour="billing"] | An element you tagged | Best |
#checkout-button | An element by id | Good |
[data-testid="save"] | An existing test hook | Good |
[aria-label="Search"] | An element by its accessible name | OK |
.sidebar > a:nth-child(3) | Position in the layout | Fragile |
.css-1x2y3z | A generated class | Avoid |
How matching works
- If a step’s selector matches nothing when the tour reaches it, that step is skipped.
- If no step’s target exists on the page, an auto-launching tour falls back to showing the launcher or welcome card instead of starting.
- If the target is inside a scrolling panel, the page scrolls just that panel to bring it into view.
- If the element is hidden (e.g. inside a closed menu), the spotlight has nothing to show — point at something visible, or use display conditions to only run the tour when it is.
Test a selector
Open your page, open the browser console and run:
document.querySelector('[data-tour="new-project"]')If it returns the element you expect, the step will find it. If it returns null, it won’t.
Something missing or unclear? Tell us and we’ll fix the page.