StepshotsOverview
A live guided tour replays a recorded flow as an interactive overlay on your own running app — it spotlights the next element and waits for the user to actually click or type it on their own account. Unlike an embedded demo, which plays back screenshots inside a player, a tour drives your real UI.
The same recording powers both: record a flow once, embed it as a screenshot demo and light the way through your live product.
Runs on your app
Spotlights real elements on your live page — not a screenshot player.
One recording
Reuses a demo you already recorded. No separate authoring step.
Show once
Auto-runs once per visitor by default — ideal for first-run onboarding.
Survives UI drift
Falls back to a step's recorded text when its selector changes.
Requirements
- The demo must be public (toggle visibility on the demo page).
- The demo must have live tour enabled — turn on "Enable live tour" in the Embed dialog's Live Tour tab. The tour endpoint stays off until you do.
- A recorded step becomes a tour step only if it has an interactive action (a click or typing) and a callout. Setup steps — navigations, waits, and steps without a callout — are skipped.
- The tour targets elements by the CSS selectors captured at record time, so it works best when you recorded against your own app (the selectors match your live DOM).
Tours are for onboarding your own product — pages where you control the markup. If a demo has no interactive-plus-callout steps, its tour is empty and nothing is shown.
Embed a tour
Copy the Live Tour snippet from the Embed dialog, or paste this on any page of your app:
<script
src="https://stepshots.com/tour.js"
data-stepshots-tour="your-demo-id"
defer
></script>That's it. On load the script fetches the tour and, when the first step's element appears, spotlights it. The tour advances as the user performs each step, waiting for elements that only mount after a navigation.
Because the tour runs on your app rather than in a sandboxed frame, add the snippet to the page(s) where the flow starts — for example, your empty-state dashboard for a "create your first project" tour.
Options
Set these as attributes on the <script> tag:
| Attribute | Default | Description |
|---|---|---|
data-stepshots-tour |
required | The demo id to run as a tour. |
data-once |
true |
Show the tour once per browser (remembered in localStorage, marked once the tour actually starts). Set "false" to run on every load. |
data-when |
— | A CSS selector that gates first-run: the tour waits until that element exists before starting (e.g. your empty state). Until then it doesn't run and isn't marked as seen. |
data-accent |
— | Spotlight ring color, any CSS color (e.g. #3b82f6) — match your brand. |
For onboarding, pair a global snippet with data-when pointed at your empty-state element (e.g. data-when="[data-empty-projects]"). A returning user who lands on a populated page won't consume their one-time run — the tour waits for the state it was recorded against.
When a tour doesn't run, the loader logs why under the [stepshots-tour] prefix in the browser console (no tour steps, already shown, or a failed fetch) — check there first while wiring it up.
Force a run for testing
Append ?tour=<demo-id> (or ?tour=1) to any URL to run the tour immediately, ignoring the once-per-browser flag. Handy for previewing and for shareable "take the tour" links:
How advancing works
The tour listens for the real interaction on the highlighted element:
- Click steps advance when the user clicks the target — and the click still does its normal job (following a link, opening a dialog, and so on).
- Typing steps advance once the user types a non-empty value into the target field.
The overlay never blocks your app: it observes the interaction and moves on. When a step's target mounts after a client-side (SPA) transition, the tour waits for it and keeps flowing. A full browser page reload ends the run, though — the overlay's state doesn't survive a fresh document load. Design tours around single-page flows, or scope multi-page onboarding to the page where the key step lives.
Surviving UI changes
Each tour step carries the target's recorded text and aria-label alongside its CSS selector. If the selector stops matching because your markup drifted, the player falls back to finding the element by that text — so a small refactor won't silently break onboarding.
Re-record the demo whenever the flow itself changes. A fresh recording refreshes both the selectors and the text fallbacks, and the tour updates everywhere it's embedded — no snippet changes needed.
Tour vs. embedded demo
| Live tour | Embedded demo | |
|---|---|---|
| Runs on | Your live app | A player (screenshots) |
| Best for | Onboarding, product walkthroughs | Marketing, docs, landing pages |
| User action | Real clicks/typing on your UI | Watch / step through |
| Where it lives | Your own pages | Anywhere (site, blog, iframe) |
| Snippet | tour.js + data-stepshots-tour |
embed.js + data-stepshots-demo |