Skip to content
awesome-tour

Type to search every page.

    BPersistenceContents

    Persistence

    Show tours once, resume where users left off, invalidate progress with versions, sync tabs and devices.

    Persistence is a plugin. Add it and a tour remembers its progress:

    import { createTour, localStorageAdapter, persist } from '@awesome-tour/react';
    const onboarding = createTour({
    id: 'onboarding',
    version: 2,
    plugins: [persist(localStorageAdapter())],
    steps: [/* … */],
    });
    Persistence · page load #1
    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%
    localStorage["awesome-tour-docs:persisted"] = null
    PersistenceDemo.tsx
    import { createTour, localStorageAdapter, persist, Tour } from '@awesome-tour/react';
    import { LoopworkApp, parts, useCreateLoopwork } from '@loopwork';
    import { RefreshCw, RotateCcw, Trash2 } from 'lucide-react';
    import { useEffect, useState } from 'react';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, StartButton, worldButton } from './ui';
    const adapter = localStorageAdapter({ prefix: 'awesome-tour-docs:' });
    const $ = parts('saved-session');
    /** Each "page load" creates a fresh tour instance, exactly like a real reload would. */
    function makeTour() {
    return createTour({
    id: 'persisted',
    version: 1,
    plugins: [persist(adapter)],
    steps: [
    {
    id: 'kick',
    target: $('row-kick'),
    title: 'Lay down the kick',
    description: 'Go a step or two in, then hit “Simulate reload”.',
    },
    {
    id: 'snare',
    target: $('row-snare'),
    title: 'Snare on 2 and 4',
    description: 'Your place is saved on every step.',
    },
    {
    id: 'hat',
    target: $('row-hat'),
    title: 'Hats keep time',
    description: 'Start again after a reload: it picks up right here.',
    },
    {
    id: 'mix',
    target: $('mixer'),
    side: 'left',
    title: 'Balance it',
    description: 'Finish it, and `once` keeps it from starting again unless forced.',
    },
    ],
    });
    }
    function readStored() {
    if (typeof window === 'undefined') return null;
    try {
    return localStorage.getItem('awesome-tour-docs:persisted');
    } catch {
    return null;
    }
    }
    /** Polls storage so the demo can show what the plugin wrote. */
    function useStored() {
    const [value, setValue] = useState(readStored);
    useEffect(() => {
    const id = setInterval(() => setValue(readStored()), 300);
    return () => clearInterval(id);
    }, []);
    return value;
    }
    export function PersistenceDemo() {
    const [load, setLoad] = useState(0);
    const [tour, setTour] = useState(makeTour);
    const stored = useStored();
    // The project outlives the simulated reloads (your app keeps its own data); the tour is rebuilt.
    const app = useCreateLoopwork();
    const reload = () => {
    tour.destroy();
    setTour(makeTour());
    setLoad((n) => n + 1);
    };
    return (
    <Tour.Root tour={tour} key={load}>
    <DemoFrame
    title={`Persistence · page load #${load + 1}`}
    actions={
    <>
    {/* restart={false}: resume instead of restarting (the Trigger's default) */}
    <StartButton restart={false} />
    <button
    type="button"
    className={worldButton.secondary}
    onClick={() => tour.start({ force: true, stepId: 'kick' })}
    >
    <RotateCcw />
    Force restart
    </button>
    <button type="button" className={worldButton.secondary} onClick={reload}>
    <RefreshCw />
    Simulate reload
    </button>
    <button
    type="button"
    className={worldButton.ghost}
    onClick={() => {
    void adapter.remove('persisted');
    reload();
    }}
    >
    <Trash2 />
    Clear storage
    </button>
    </>
    }
    footer={
    <pre className="overflow-x-auto font-mono whitespace-pre-wrap">
    localStorage["awesome-tour-docs:persisted"] = {stored ?? 'null'}
    </pre>
    }
    >
    <LoopworkApp scope="saved-session" layout="compact" app={app} />
    </DemoFrame>
    <TourPopover />
    </Tour.Root>
    );
    }

    What it does

    Option Default Effect
    resume true start() continues from the last step seen.
    once true Completed or skipped tours don’t start again — unless start({ force: true }).
    persistData false Also save tour.data (answers, choices).
    sync true Finishing the tour in one tab closes it in the others.
    key tour id Storage key for a tour id.

    Tour.Trigger is meant for “Take the tour again” buttons, so it restarts by default (force). Use <Tour.Trigger restart={false}> to resume instead.

    Versioning. Saved progress records the tour’s version. When you change a tour meaningfully, bump version and everyone sees it again from the start.

    Adapters

    • localStorageAdapter({ prefix }) — default prefix awesome-tour:; cross-tab sync via the storage event.
    • memoryStorage() — for tests and SSR.
    • Your own: anything implementing get, set, remove (sync or async), optionally subscribe.

    Saving to your backend makes onboarding follow users across devices:

    import type { PersistenceAdapter } from '@awesome-tour/react';
    const serverAdapter: PersistenceAdapter = {
    get: (key) => fetch(`/api/tours/${key}`).then((r) => (r.ok ? r.json() : null)),
    set: (key, value) =>
    fetch(`/api/tours/${key}`, { method: 'PUT', body: JSON.stringify(value) }).then(() => {}),
    remove: (key) => fetch(`/api/tours/${key}`, { method: 'DELETE' }).then(() => {}),
    };
    createTour({ id: 'onboarding', plugins: [persist(serverAdapter)], steps });

    Read saved progress without starting a tour (e.g. to show a “Resume tour” button) with readTourProgress(adapter, tourId, { key }).

    Checklists use the same adapters — see Onboarding checklist. Full API in the persistence reference.