Skip to content
awesome-tour

Type to search every page.

    BTargetsContents

    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.

    Target types
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    TargetsDemo.tsx
    import {
    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.