Feature Library

Guided tour: spotlight and coach marks

<0.01 CPU ms
A still of the Guided tour: spotlight and coach marks demo
Still
The live demo starts when it’s in view.Follow the tour with the buttons or the arrow keys · click New note when asked · Esc ends it · ? starts it again

Onboarding steps attached to parts of the page.

What it costs a frame

<0.01 ms
GPU
not used
CPU, median
<0.01 ms
CPU, 95th pct
<0.01 ms
Draw calls
0
Weight
Light

Measured 7 November 2026 on 13th Gen Intel(R) Core(TM) i9-13900H, Chrome 156, 1920×1080 at 1×. 600 frames × 3 rounds, median kept. What ran: Measured with the tour driving itself: one step every 40 frames through all eight, gliding the spotlight and popover between targets (one read and one write a frame while it glides), scrolling the list to the last targets, waiting for a note that appears 600 ms after it is asked for, then ending and starting again. Between steps nothing runs: no timers, no animation frames. Phones: tiers are being measured next.

On every machine it was measured on
MachineGPU msCPU msCPU p95
unknown GPU · 13th Gen Intel(R) Core(TM) i9-13900Hreference · measuring toolnot timed<0.01<0.01
apple · Apple A19 Proin a browser tab · 16 November 2026not timed<0.010.02
Intel Arc 140V (Xe2-LPG) · Intel Core Ultra 7 258Vin a browser tab · 15 November 2026not timed<0.01<0.01

Bars against one 16.7 ms frame. A browser-tab run is timed in a visible tab without the tool’s scripted input, so read it as close, not exact.

What it needs

Renders with
DOM and CSSPlain DOM and CSS: every current browser.
Your browser
Runs hereNo WebGPU needed
Depends on
NothingNo other packages

What it’s for

  1. A first-run tour of a new app
  2. Showing what changed after a release
  3. Teaching a feature by having people use it ("now click Save")
  4. Help that points at the control it is about
  5. Empty states that lead into the first action

Pitfalls, in brief

  1. The tour follows its target through scrolling, resizes of the target, its parent and the page, and the end of any transition or animation.
  2. Selectors are looked up when the step shows, not when the tour is made.
  3. advanceOn moves the tour on after the event has finished, on a timeout of 0, so the app’s own handler runs first.
  4. A host other than document.body must be positioned and should not scroll itself, or the layer scrolls away with the content.
  5. The dimmed page is not inert: it is a non-modal dialog, so Tab can leave the popover and outside: "pass" lets presses through.
3 more in brief
  1. "Don’t show again" is only a box: the tour keeps nothing.
  2. Import guided-tour.base.css before guided-tour.css.
  3. Nothing runs between changes, so a target moved by a CSS transform or animation is caught up only when that motion ends (transitionend, animationend).
8 pitfalls in full, the hook-up guide, the module source and its tests come with the part.

Where it comes from

Written for the library. Fully custom code.

WAI-ARIA Authoring Practices Guide (W3C): The dialog pattern’s guidance for a non-modal dialog: role=dialog without aria-modal, named by its title and described by its text (aria-describedby), focus moved into it and given back at the end, Esc to close, and F6 to move between it and the page. Written here from scratch.

onboardingguided tourcoach marksspotlightwalkthroughpopovernon-modal dialogplacementflipbottom sheetMutationObserverResizeObserveraccessibilitykeyboardtouchrtldomcssno dependencies

Near it in the frame