Skip to content
awesome-tour

Type to search every page.

    BMulti-page toursContents

    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.
    Multi-page
    Loopworknight-drive.lwp
    001.1.1
    1. 1
    2. 2
    3. 3
    4. 4
    5. 5
    6. 6
    7. 7
    8. 8
    Drums
    Beat A
    Beat B
    Bass
    Sub line
    Keys
    Rhodes
    Vox
    Hook (dry)

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap
    MultiPageDemo.tsx
    import { 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 component
    function 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 project

    See the router reference for the full adapter interface.