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: [/* … */],});Beat A
16 steps · drumsMixer
4 channelslocalStorage["awesome-tour-docs:persisted"] = null
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 prefixawesome-tour:; cross-tab sync via thestorageevent.memoryStorage()— for tests and SSR.- Your own: anything implementing
get,set,remove(sync or async), optionallysubscribe.
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.