Skip to content
awesome-tour

Type to search every page.

    BDisplay rulesContents

    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.

    Display rules
    User plan
    Move the clock forward
    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

    Day 1 of the campaign · open the Mix page to trigger it → …

      RulesDemo.tsx
      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:

      Help when they're stuck
      Loopworknight-drive.lwp
      001.1.1

      Mixer

      4 channels
      Drums
      80%
      Bass
      35%
      Keys
      60%
      Vox
      50%

      Bounce

      8 bars · 0:21
      Renders the loop to one file.
      Hover the mixer, triple-click Stems, or wait 8 s.
      BehaviorDemo.tsx
      import { 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.