Targets
Point steps at elements with selectors, refs, anchors, virtual elements — and handle targets that load late or never.
A step’s target is what gets highlighted and what the content is positioned against. Leave it out
for a centered step.
Beat A
16 steps · drumsMixer
4 channelsimport { anchor, byRole, createAnchorRegistry, createTour, Tour, useTourAnchor, type VirtualElement,} from '@awesome-tour/react';import { LoopworkApp, Mixer, parts, Sequencer, Transport, useCreateLoopwork } from '@loopwork';import { useRef, useState } from 'react';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton } from './ui';
// A registry scoped to this demo, so its anchor names can't clash with other demos on the page.const anchors = createAnchorRegistry();const $ = parts('aim');
export function TargetsDemo() { const app = useCreateLoopwork(); const sequencerRef = useRef<HTMLDivElement>(null); const mixerRef = useTourAnchor<HTMLDivElement>('mixer', anchors);
// Not an element: a rect computed every frame. Here, the kick cell under the playhead. const [nowPlaying] = useState<VirtualElement>(() => ({ getBoundingClientRect() { const cell = document.querySelector(`#aim [data-cell="0:${app.getState().step}"]`); return (cell ?? document.body).getBoundingClientRect(); }, }));
const [tour] = useState(() => createTour({ id: 'docs-targets', anchors, steps: [ { id: 'selector', target: $('transport'), title: 'By selector', description: 'A CSS selector string. It pierces open shadow roots too.', }, { id: 'role', target: byRole('button', { name: 'Export', exact: true, within: '#aim' }), title: 'By role and name', description: 'The button a user would call “Export”. Survives any markup refactor.', }, { id: 'ref', target: sequencerRef, title: 'By React ref', description: 'The ref’s element, resolved when the step starts.', }, { id: 'anchor', target: anchor('mixer'), side: 'left', title: 'By anchor', description: 'The mixer registers itself as “mixer”. No selector to break.', }, { id: 'virtual', target: nowPlaying, beforeEnter: () => app.play(), afterLeave: () => app.stop(), title: 'A moving rect', description: 'A virtual element: the cell under the playhead, measured every frame.', }, { id: 'many', target: [$('row-kick'), $('row-clap')], title: 'Several targets', description: 'An array highlights them together.', }, { id: 'missing', target: $('mastering'), targetTimeout: 800, title: 'Not on the page', description: 'After targetTimeout the step falls back to the center.', }, ], }), );
return ( <Tour.Root tour={tour}> <DemoFrame title="Target types" actions={<StartButton />}> <LoopworkApp scope="aim" app={app} layout="custom"> <Transport /> <div className="grid min-w-0 @3xl:grid-cols-[minmax(0,1.5fr)_minmax(0,1fr)]"> <div ref={sequencerRef} className="border-b @3xl:border-r @3xl:border-b-0"> <Sequencer /> </div> <div ref={mixerRef}> <Mixer /> </div> </div> </LoopworkApp> </DemoFrame> <TourPopover /> </Tour.Root> );}Target types
target |
Notes |
|---|---|
'#search' |
CSS selector. Also searches inside open shadow roots. |
element |
Any Element. |
ref |
A React ref ({ current }), read when the step starts. |
anchor('mixer') |
A named anchor registered from your components. Recommended. |
byTour('mixer') |
Elements with data-tour="mixer". See resilient targets. |
byRole('button', { name: 'Export' }) |
By ARIA role and accessible name, like Testing Library. |
byText('Bounce') |
The innermost element with this text. |
firstOf(a, b, c) |
The first candidate that resolves: a fallback chain. |
() => document.querySelector('.row') |
A function returning any of the above, called on resolution. |
{ getBoundingClientRect } |
A virtual element: canvas regions, 3D objects, text… |
['#a', '#b'] |
Several targets: the highlight covers the union of their rects. |
Anchors
Selectors couple tours to markup. Anchors invert that: components register themselves under a name, and steps refer to the name.
import { anchor, createTour, Tour, useTourAnchor } from '@awesome-tour/react';
const tour = createTour({ id: 'billing', steps: [{ id: 'plan', target: anchor('plan-picker'), title: 'Pick a plan' }],});
function PlanPicker() { const ref = useTourAnchor<HTMLDivElement>('plan-picker'); return <div ref={ref}>…</div>;}
// or, without a hook:<Tour.Anchor name="plan-picker" asChild> <PlanPicker /></Tour.Anchor>;If the anchored component mounts after the step starts (a lazy route, a modal opening), the tour
waits for it — see below. Anchors live in a registry; the global one is used by default, and
TourProvider or createTour({ anchors }) can scope them with createAnchorRegistry().
Resilient targets
Class names and DOM structure change with every refactor; what users see changes much less. These helpers find elements the way people (and Testing Library) do, and each returns an ordinary target:
import { byRole, byText, byTour, firstOf } from '@awesome-tour/react';
{ target: byTour('mixer') } // [data-tour="mixer"]{ target: byRole('slider', { name: 'Bass level' }) } // role + accessible name{ target: byRole('button', { name: /export/i, within: '#transport' }) }{ target: byText('Bounce your first loop') }
// Old builds still have #export-btn: try the stable locator first, fall back to the selector.{ target: firstOf(byTour('export'), byRole('button', { name: 'Export' }), '#export-btn') }byRole understands explicit roles and the implicit ones of common elements (<button>, links,
headings, form fields, <nav>, <main>…); the accessible name comes from aria-labelledby,
aria-label, <label>, alt, then the text. All of them search open shadow roots and accept
within to scope the search. Devtools’ element picker suggests the most stable one for any
element you click.
An array means “all of these at once” (one highlight around them); firstOf means “the first one
that exists”.
Async and missing targets
When a step starts, the tour waits for its target: it watches the DOM (MutationObserver) and
the anchor registry until the target shows up or targetTimeout (default 3000 ms) passes. Then
onTargetMissing decides:
| Policy | Behavior |
|---|---|
'center' (default) |
Show the step centered. data-target-missing is set on the content. |
'wait' |
Keep waiting with no timeout — for content that loads slowly. |
'skip' |
Skip to the next step, in the current direction. |
'error' |
Stop the tour with an error (state.error, error event). |
Both options can be set per step or as tour-wide defaults:
createTour({ id: 'reports', targetTimeout: 5000, onTargetMissing: 'skip', steps: [ { id: 'chart', target: '#chart', onTargetMissing: 'wait' }, // async widget { id: 'beta', target: anchor('beta-flag') }, // skipped for users without the flag ],});A targetMissing event fires whenever a target couldn’t be found — useful for catching stale tours
in production (the analytics plugin reports it as target_missing).
Scrolling
Targets are scrolled into view before the step is shown, including inside nested scroll containers.
Disable or customize per step or tour-wide with scroll: false or scroll: ScrollIntoViewOptions.
Layout changes are tracked automatically (resize, scroll, DOM mutations). If you move a target in a
way that can’t be observed, call tour.refresh() to resolve it again.
Virtual elements
Anything with getBoundingClientRect() can be a target. That’s how
@awesome-tour/three highlights objects in a WebGL scene:
const selection = window.getSelection()!.getRangeAt(0);
tour.goTo('explain-selection'); // with target: () => ({// getBoundingClientRect: () => selection.getBoundingClientRect(),// contextElement: document.querySelector('#editor')!,// })Set contextElement so the tour can find the scroll ancestors of a virtual element.
Inside iframes
frameTarget points a step at an element inside a same-origin <iframe> — an embedded editor,
a preview, a sandboxed widget. It resolves lazily, so the tour waits for the frame and its content:
import { frameTarget } from '@awesome-tour/react';
{ id: 'save', target: frameTarget('#preview', '#save-button'), title: 'Save from the preview' }The frame can be an element, a selector or a function; the inner target a selector or
(doc) => Element. Cross-origin frames can’t be read, so their targets never resolve — use
onTargetMissing to decide what happens.