Skip to content
awesome-tour

Type to search every page.

    BMultiple toursContents

    Multiple tours

    Register many tours in one app, start them by id, and let a queue decide which one is on screen.

    Real apps have many tours: the main onboarding, a “what’s new” for each release, a tour per feature. TourProvider registers them and makes sure only one is on screen at a time.

    import { Tour, TourProvider, useTour } from '@awesome-tour/react';
    export function App() {
    return (
    <TourProvider tours={[onboarding, whatsNew, reportsTour]} router={router}>
    <Routes />
    {/* One Tour.Root per tour, rendered wherever its UI should live */}
    <Tour.Root tourId="onboarding">
    <OnboardingCard />
    </Tour.Root>
    <Tour.Root tourId="whats-new">
    <AnnouncementCard />
    </Tour.Root>
    </TourProvider>
    );
    }
    function HelpMenu() {
    const { start } = useTour('reports'); // look up a registered tour by id
    return <button onClick={() => start()}>Tour the reports page</button>;
    }
    Queue and priority
    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%

    Start the onboarding, then ask for “What’s new”: it waits its turn.

    on screen: — · queue: []

    MultipleToursDemo.tsx
    import {
    createTour,
    Tour,
    TourProvider,
    useStoreSelector,
    useTourManager,
    } from '@awesome-tour/react';
    import { createAnnouncement } from '@awesome-tour/react/surfaces';
    import { LoopworkApp, parts } from '@loopwork';
    import { Layers, Play, Zap } from 'lucide-react';
    import { AnnouncementModal } from '@/components/awesome-tour/announcement';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, worldButton } from './ui';
    const $ = parts('queue');
    const firstSession = createTour({
    id: 'first-session',
    steps: [
    {
    id: 'transport',
    target: $('transport'),
    title: 'Transport',
    description: 'Play, stop, record.',
    },
    {
    id: 'beat',
    target: $('sequencer'),
    title: 'The beat',
    description: 'Sixteen steps per bar.',
    },
    {
    id: 'mixer',
    target: $('mixer'),
    side: 'left',
    title: 'Mixer',
    description: 'Levels per channel.',
    },
    ],
    });
    const whatsNew = createAnnouncement({
    id: 'whats-new',
    variant: 'modal',
    title: 'Loopwork 2.4',
    description: 'Swing per row, wider meters, and a faster bounce.',
    });
    const saveWarning = createTour({
    id: 'unsaved',
    steps: [
    {
    id: 'save',
    target: $('transport'),
    title: 'Unsaved changes',
    description: 'You’re about to leave night-drive. This interrupts whatever was on screen.',
    },
    ],
    });
    function Controls() {
    const manager = useTourManager();
    return (
    <>
    <button
    type="button"
    className={worldButton.primary}
    onClick={() => void manager.start('first-session', { force: true })}
    >
    <Play aria-hidden="true" />
    Onboarding
    </button>
    <button
    type="button"
    className={worldButton.secondary}
    onClick={() => void manager.start('whats-new', { force: true, priority: 10 })}
    >
    <Layers aria-hidden="true" />
    What’s new
    </button>
    <button
    type="button"
    className={worldButton.secondary}
    onClick={() => void manager.start('unsaved', { force: true, interrupt: true })}
    >
    <Zap aria-hidden="true" />
    Interrupt
    </button>
    </>
    );
    }
    function QueueState() {
    const manager = useTourManager();
    const state = useStoreSelector(manager, (s) => s);
    return (
    <p className="font-mono tabular-nums">
    on screen: {state.activeId ?? '—'} · queue: [{state.queue.join(', ')}]
    </p>
    );
    }
    export function MultipleToursDemo() {
    return (
    <TourProvider tours={[firstSession, whatsNew, saveWarning]}>
    <DemoFrame
    title="Queue and priority"
    actions={<Controls />}
    footer={
    <div className="flex flex-col gap-1">
    <p>Start the onboarding, then ask for “What’s new”: it waits its turn.</p>
    <QueueState />
    </div>
    }
    >
    <LoopworkApp scope="queue" layout="compact" />
    </DemoFrame>
    <Tour.Root tourId="first-session">
    <TourPopover />
    </Tour.Root>
    <Tour.Root tourId="unsaved">
    <TourPopover />
    </Tour.Root>
    <AnnouncementModal announcement={whatsNew} actionLabel="Got it" />
    </TourProvider>
    );
    }

    Queue and priority

    Starting a tour through the manager while another is on screen queues it; it starts when the current one finishes. Higher priority goes first; interrupt closes whatever is showing.

    const manager = useTourManager();
    manager.start('whats-new', { priority: 1 }); // after onboarding, before priority-0 tours
    manager.start('security-alert', { interrupt: true }); // right now

    Tour.Trigger and the open prop of Tour.Root go through the manager when the tour is registered on a provider. Calling tour.start() directly bypasses the queue.

    useStoreSelector(manager) gives you { activeId, queue, tourIds } — e.g. to hide a chat widget while any tour is active:

    const activeId = useStoreSelector(useTourManager(), (s) => s.activeId);

    Outside React

    The provider wraps createTourManager() from the core, which you can also create yourself and pass as <TourProvider manager={manager}>. See the manager reference.