Display rules
Who sees a tour, when, and how often — targeting, scheduling, frequency caps, snooze and automatic triggers, with an explanation when a tour doesn't show.
A tour with rules decides by itself whether it should appear. The
tour manager (the one inside TourProvider) evaluates them, starts tours
when their trigger fires, and remembers impressions — how often each tour was shown, how it ended,
when it was snoozed.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsDay 1 of the campaign · open the Mix page to trigger it → …
import { createTour, createTourManager, type EligibilityReport, Tour, TourProvider, useTour,} from '@awesome-tour/react';import { LoopworkApp, parts, useCreateLoopwork } from '@loopwork';import { Check, FastForward, RotateCcw, X } from 'lucide-react';import { useEffect, useState } from 'react';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, worldButton } from './ui';
const $ = parts('campaign');const DAY = 86_400_000;
// A fake clock the demo can fast-forward. In your app, leave `clock` out (it's Date.now).let offset = 0;const clock = () => Date.now() + offset;const launch = Date.now();
interface Data { plan: 'free' | 'pro';}
const tour = createTour({ id: 'docs-stems-campaign', modal: false, data: { plan: 'free' } as Data, steps: [ { id: 'stems', target: $('format-stems'), title: 'Stems are unlocked', description: 'Pro plan: bounce one file per channel and finish the mix anywhere.', }, ], rules: { audience: ({ data }) => data.plan === 'pro', schedule: { startsAt: launch, endsAt: launch + 14 * DAY }, // a two-week campaign trigger: { signal: 'mix-opened' }, frequency: { once: 'completed', maxShows: 3, cooldownMs: DAY }, },});
const manager = createTourManager({ tours: [tour], clock, connect: false });
function SnoozeButton() { const { tour: current } = useTour(); return ( <button type="button" className={worldButton.ghost} onClick={() => current.snooze(2 * DAY)}> Remind me in 2 days </button> );}
const JUMPS = [ { label: '+1 h', ms: 3_600_000 }, { label: '+1 day', ms: DAY }, { label: '+1 week', ms: 7 * DAY },];
function Campaign() { const app = useCreateLoopwork({ route: 'arrange' }); const plan = useLoopworkPlan(app); const [report, setReport] = useState<EligibilityReport | null>(null); const [now, setNow] = useState(clock);
// The app reports what the user does; the manager decides whether the tip may show. useEffect(() => { const offs = [ app.on('route-changed', () => { if (app.getState().route === 'mix') manager.signal('mix-opened'); }), manager.connect(), ]; return () => { for (const off of offs) off(); }; }, [app]);
// biome-ignore lint/correctness/useExhaustiveDependencies: the fake clock moving doesn't notify anyone: re-explain when it does useEffect(() => { const refresh = () => void manager.explain(tour.id).then(setReport); refresh(); const offs = [ manager.subscribe(refresh), tour.subscribe(refresh), // Impressions are written after the event that causes them: re-explain once they land. tour.on('snooze', () => setTimeout(refresh, 0)), tour.on('complete', () => setTimeout(refresh, 0)), ]; return () => { for (const off of offs) off(); }; }, [now]);
const jump = (ms: number) => { offset += ms; setNow(clock()); };
return ( <DemoFrame title="Display rules" actions={ <> <fieldset className="flex items-center rounded-sm border-2 border-ink"> <legend className="sr-only">User plan</legend> {(['free', 'pro'] as const).map((p) => ( <button key={p} type="button" aria-pressed={plan === p} onClick={() => { app.setPlan(p); tour.setData({ plan: p }); }} className={`${worldButton.secondary} h-8 rounded-none border-0 capitalize`} > {p} </button> ))} </fieldset> <fieldset className="flex items-center rounded-sm border-2 border-ink"> <legend className="sr-only">Move the clock forward</legend> {JUMPS.map((j) => ( <button key={j.label} type="button" onClick={() => jump(j.ms)} className={`${worldButton.secondary} h-8 rounded-none border-0 font-mono`} > <FastForward aria-hidden="true" /> {j.label} </button> ))} </fieldset> <button type="button" className={worldButton.ghost} onClick={() => { offset = 0; setNow(clock()); tour.close(); void manager.resetImpressions(); app.reset({ route: 'arrange' }); }} > <RotateCcw aria-hidden="true" /> Reset </button> </> } footer={ <div className="flex flex-col gap-1.5"> <p className="font-semibold text-ink"> <span className="font-mono"> Day {Math.floor((now - launch) / DAY) + 1} of the campaign </span>{' '} · open the Mix page to trigger it →{' '} <span className={report?.eligible ? 'text-ink' : 'text-dont'}> {report ? (report.eligible ? 'eligible' : 'blocked') : '…'} </span> </p> <ul aria-label="Rule checks" className="grid gap-1 font-mono sm:grid-cols-2"> {report?.checks.map((c) => ( <li key={c.rule} className="flex items-center gap-2"> {c.ok ? ( <Check className="size-3.5 shrink-0" aria-label="passes" /> ) : ( <X className="size-3.5 shrink-0 text-dont" aria-label="fails" /> )} <span className="font-semibold text-ink">{c.rule}</span> <span className="truncate">{c.detail}</span> </li> ))} </ul> </div> } > <LoopworkApp scope="campaign" app={app} layout="routed" /> </DemoFrame> );}
function useLoopworkPlan(app: ReturnType<typeof useCreateLoopwork>) { const [plan, setPlan] = useState(app.getState().plan); useEffect(() => app.subscribe(() => setPlan(app.getState().plan)), [app]); return plan;}
export function RulesDemo() { return ( <TourProvider manager={manager}> <Tour.Root tour={tour}> <Campaign /> <TourPopover overlay={false} progress={false}> <SnoozeButton /> </TourPopover> </Tour.Root> </TourProvider> );}Try it: on the free plan, opening the Mix page does nothing — the audience rule blocks it.
Switch to pro and open Mix again. Snooze it, then fast-forward the clock: the snooze, the
one-day cooldown and the two-week schedule all expire on the demo’s clock
(createTourManager({ clock })).
Rules
const tour = createTour({ id: 'billing-tips', steps, rules: { audience: ({ data }) => data.plan === 'pro', // targeting schedule: { startsAt: '2026-12-01', endsAt: '2027-01-15' }, // a dated campaign frequency: { once: true, maxShows: 3, cooldownMs: 86_400_000 }, trigger: { route: '/billing/*' }, // start by itself priority: 10, },});| Rule | Passes when |
|---|---|
audience |
audience({ data }) returns true (may be async — fetch a feature flag here). |
schedule |
Now is between startsAt and endsAt (Date, ISO string or timestamp). |
once |
true (default): never completed, skipped or dismissed. 'completed': never completed or skipped — closing it with Esc isn’t final. 'seen': never shown. false: off. |
dismissCooldownMs |
After a dismissal (close, Esc), at least this long has passed. Pairs with once: 'completed'. |
maxShows |
It was shown fewer than maxShows times. |
cooldown |
At least cooldownMs passed since it was last shown. |
snooze |
Any tour.snooze(ms) has expired. |
Triggers
trigger starts the tour by itself, when it’s eligible and no other tour is on screen (a
triggered tour never interrupts or queues behind another one — it gets its chance next time).
| Trigger | Fires when |
|---|---|
route |
The router reaches a matching path (/projects/:id, /docs/*). |
signal |
Your app calls manager.signal(name) — after a feature is used, a plan changes… |
event |
A DOM event happens on (or inside) a target: { type: 'click', target: '#help' }. |
delay |
This many ms after the tour is registered. |
targetVisible |
A target appears on the page. |
dwell |
The pointer rests on (or focus stays in) a target for ms (default 2000): { target: '#mixer', ms: 1500 }. |
idle |
No pointer, key, wheel or scroll activity for this many ms. |
rageClick |
clicks (3) fast clicks within within ms (800) on one element, optionally inside target. |
repeat |
manager.signal(signal) happened times times (2), optionally within ms: the same error twice. |
A first visit to a page is trigger: { route } with the default once.
Help when they’re stuck
The last four don’t wait for a page or a button: they react to how people behave. Hover the mixer for a moment, triple-click the locked Stems format, or leave the page alone for 8 seconds:
Mixer
4 channelsBounce
8 bars · 0:21import { createTour, createTourManager, Tour, TourProvider } from '@awesome-tour/react';import { ExportPanel, LoopworkApp, Mixer, parts, Transport } from '@loopwork';import { RotateCcw } from 'lucide-react';import { useEffect, useRef, useState } from 'react';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, worldButton } from './ui';
const $ = parts('stuck');
// Each tip waits for a sign that the user is stuck, then shows once.const lingering = createTour({ id: 'tip-mixer', modal: false, scroll: false, rules: { trigger: { dwell: { target: $('mixer'), ms: 1500 } }, frequency: { maxShows: 1 } }, steps: [ { id: 'tip', target: $('mixer'), side: 'start', title: 'Looking for the levels?', description: 'Drag a knob up, or focus it and press ↑. You lingered here, so here’s the tip.', }, ],});
const frustrated = createTour({ id: 'tip-stems', modal: false, scroll: false, rules: { trigger: { rageClick: { target: $('format-stems'), clicks: 3 } }, frequency: { maxShows: 1 }, }, steps: [ { id: 'tip', target: $('format-stems'), title: 'Stems are a Pro feature', description: 'Three clicks on a locked option: you clearly want it. WAV is free meanwhile.', }, ],});
const idle = createTour({ id: 'tip-idle', modal: false, scroll: false, rules: { trigger: { idle: 8000 }, frequency: { maxShows: 1 } }, steps: [ { id: 'tip', target: $('play'), title: 'Need a hand?', description: 'Nothing happened for 8 seconds. Press play to hear what’s there.', }, ],});
const tips = [lingering, frustrated, idle];const manager = createTourManager({ tours: tips, connect: false });
function Log() { const [fired, setFired] = useState<string[]>([]); useEffect(() => { const offs = tips.map((tip) => tip.on('start', () => setFired((f) => [...f, tip.id]))); return () => { for (const off of offs) off(); }; }, []); return ( <span className="font-mono"> {fired.length ? `started: ${fired.join(', ')}` : 'Hover the mixer, triple-click Stems, or wait 8 s.'} </span> );}
export function BehaviorDemo() { // The triggers listen to the whole document: arm them only while the demo is on screen, so // reading the docs above it doesn't count as being idle. const ref = useRef<HTMLDivElement>(null); useEffect(() => { const el = ref.current; if (!el || typeof IntersectionObserver === 'undefined') return manager.connect(); let disconnect: (() => void) | null = null; const io = new IntersectionObserver(([entry]) => { if (entry?.isIntersecting && !disconnect) disconnect = manager.connect(); else if (!entry?.isIntersecting && disconnect) { disconnect(); disconnect = null; } }); io.observe(el); return () => { io.disconnect(); disconnect?.(); }; }, []); return ( <TourProvider manager={manager}> <div ref={ref}> <DemoFrame title="Help when they're stuck" actions={ <button type="button" className={worldButton.ghost} onClick={() => { for (const tip of tips) tip.close(); void manager.resetImpressions(); }} > <RotateCcw aria-hidden="true" /> Reset </button> } footer={<Log />} > <LoopworkApp scope="stuck" layout="custom"> <Transport /> <div className="grid min-w-0 @3xl:grid-cols-[minmax(0,1.2fr)_minmax(0,1fr)]"> <Mixer className="border-b @3xl:border-r @3xl:border-b-0" /> <ExportPanel /> </div> </LoopworkApp> </DemoFrame> </div> {tips.map((tip) => ( <Tour.Root key={tip.id} tour={tip}> <TourPopover overlay={false} progress={false} /> </Tour.Root> ))} </TourProvider> );}Snooze
tour.snooze(ms) closes the tour and keeps it from auto-starting until the time is up — the
“Remind me tomorrow” button:
function RemindLater() { const { tour } = useTour(); return <button onClick={() => tour.snooze(24 * 60 * 60 * 1000)}>Remind me tomorrow</button>;}Across tours
Rules are per tour; users experience all of them together. A manager-wide cap keeps automatic tours, announcements and surveys from piling up:
const manager = createTourManager({ tours, cap: { perSession: 1, cooldownMs: 24 * 60 * 60_000 }, // one a session, a day apart});When a tour’s content changes, frequency.perVersion makes it eligible again for people who
finished an older version — release notes that come back for each release:
createTour({ id: 'whats-new', version: 24, rules: { frequency: { once: true, perVersion: true } }, steps });Remembering impressions
By default impressions live in memory (lost on reload). Give the provider any persistence adapter to keep them — in the browser or on your server:
import { localStorageAdapter, TourProvider } from '@awesome-tour/react';
const impressions = localStorageAdapter({ prefix: 'tour-impressions:' });
<TourProvider tours={tours} router={router} impressions={impressions}>…</TourProvider>;Why didn’t my tour show?
manager.explain(id) returns every rule’s verdict with a reason:
const report = await manager.explain('billing-tips');// { eligible: false, checks: [// { rule: 'audience', ok: false, detail: 'audience() returned false' },// { rule: 'once', ok: true, detail: 'not finished yet' },// ] }The devtools Rules tab shows the same report for every tour, live, with buttons to start a tour if eligible and reset impressions.