Multi-page tours
Tours that follow the user across routes, with adapters for React Router, Next.js and TanStack Router.
Give a step a route and the tour navigates there before resolving its target:
const onboarding = createTour({ id: 'onboarding', steps: [ { id: 'home', route: '/', target: '#stats' }, { id: 'projects', route: '/projects', target: '#project-list' }, { id: 'widget', route: '/projects', target: '#analytics', onTargetMissing: 'wait' }, ],});- Going back navigates back to the previous step’s route.
- If the user navigates away while a step is shown, the step is hidden (phase
resolving) and reappears when they return to its route. - The new page’s targets are awaited like any async target.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsimport { createTour, type RouterAdapter, Tour } from '@awesome-tour/react';import { createLoopwork, LoopworkApp, parts, type Route, sampleSlug } from '@loopwork';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton } from './ui';
const $ = parts('session');const app = createLoopwork({ route: 'arrange' });
/** Loopwork's pages, seen through a RouterAdapter — the same shape React Router's adapter has. */const router: RouterAdapter = { getPath: () => `/${app.getState().route}`, navigate: (path) => app.navigate(path.slice(1) as Route), subscribe: (listener) => app.subscribe(listener),};
const RHODES = 'Keys rhodes 11';
const tour = createTour({ id: 'docs-multi-page', router, steps: [ { id: 'beat', route: '/arrange', target: $('sequencer'), title: 'Sketch on Arrange', description: 'The beat is down. Next we pick a sound on another page.', }, { id: 'sample', route: '/library', // The list is virtualized: row 356 doesn't exist until it's scrolled to. beforeEnter: () => app.revealSample(RHODES), target: $(sampleSlug(RHODES)), title: 'A Rhodes loop', description: 'The tour opened Library and scrolled 400 samples to this one.', }, { id: 'mix', route: '/mix', target: $('knob-keys'), side: 'left', title: 'Then balance it on Mix', description: 'Press Back: the tour walks you back across pages.', }, { id: 'bounce', route: '/mix', target: $('bounce'), title: 'And bounce', description: 'Leave this page with the tabs above: the step hides until you return.', }, ],});
export function MultiPageDemo() { return ( <Tour.Root tour={tour}> <DemoFrame title="Multi-page" actions={<StartButton onClick={() => app.navigate('arrange')} />} > <LoopworkApp scope="session" app={app} layout="routed" /> </DemoFrame> <TourPopover /> </Tour.Root> );}Router adapters
The tour talks to your router through a tiny RouterAdapter. Pass one to TourProvider (shared by
all tours) or to createTour({ router }).
import { useReactRouterAdapter } from '@awesome-tour/router/react-router';
// Render inside <RouterProvider> / <BrowserRouter>function TourProviders({ children }) { const router = useReactRouterAdapter(); return ( <TourProvider tours={[onboarding]} router={router}> {children} </TourProvider> );}'use client';import { useNextRouterAdapter } from '@awesome-tour/router/next';
// app/providers.tsx (App Router)export function Providers({ children }) { const router = useNextRouterAdapter({ scroll: false }); return ( <TourProvider tours={[onboarding]} router={router}> {children} </TourProvider> );}import { useTanStackRouterAdapter } from '@awesome-tour/router/tanstack-router';
// Render inside <RouterProvider>, e.g. in your root route componentfunction TourProviders({ children }) { const router = useTanStackRouterAdapter(); return ( <TourProvider tours={[onboarding]} router={router}> {children} </TourProvider> );}import { useRouterAdapter } from '@awesome-tour/react';
function TourProviders({ children }) { const { pathname, push } = useMyRouter(); const router = useRouterAdapter({ pathname, navigate: push }); return <TourProvider router={router}>{children}</TourProvider>;}The React adapters resolve navigate() only once the new pathname has been rendered, so the tour
never looks for targets on the old page. They match routes with matchRoute (the default for every adapter),
which supports :params and a trailing * (/projects/:id, /settings/*); pass match to
customize.
Install with pnpm add @awesome-tour/router — each router is an optional peer dependency, imported
from its own subpath.
Without React
createBrowserRouter() from the core uses the History API (pushState + popstate):
import { createBrowserRouter, createTour } from '@awesome-tour/core';
createTour({ id: 'docs', router: createBrowserRouter({ base: '/app' }), steps: [/* … */] });Patterns and failed navigation
A step is shown only once the current path matches its route — targets are never looked up on
the wrong page:
- Concrete paths (
/projects/demo) are navigated to. If navigation doesn’t land (an auth guard redirects, the adapter times out), the step stays hidden until the user gets there. - Patterns (
/projects/:id,/settings/*) can’t be navigated to — the tour doesn’t know which project to open. The step waits, hidden, until the user opens a matching page:
{ id: 'project-header', route: '/projects/:id', target: '#project-header' } // any projectSee the router reference for the full adapter interface.