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>;}Beat A
16 steps · drumsMixer
4 channelsStart the onboarding, then ask for “What’s new”: it waits its turn.
on screen: — · queue: []
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 toursmanager.start('security-alert', { interrupt: true }); // right nowTour.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.