Tour manager
Coordinate several tours so only one is on screen at a time, with a priority queue and interruption.
import { createTourManager } from '@awesome-tour/core';
const manager = createTourManager({ tours: [onboarding, whatsNew], router });
manager.start('onboarding');manager.start('whats-new'); // queued until onboarding finishesIn React, TourProvider creates a manager for you (useTourManager() returns it), and useTour('id') / <Tour.Root tourId="id"> look tours up in it.
createTourManager(options?)
| Option | Type | Description |
|---|---|---|
tours |
Tour[] |
Tours to register immediately. |
router |
RouterAdapter |
Router adapter given to every registered tour (tour.setRouter). |
impressions |
PersistenceAdapter<ImpressionRecord> |
Where display rules remember shows, outcome and snooze. Default: in memory. TourProvider takes it as a prop. |
cap |
{ perSession?, cooldownMs? } |
A frequency cap across every tour, announcement and survey the manager starts by itself (triggers, startIfEligible): at most perSession per page session, cooldownMs between two. Reported as the cap rule by explain(). Explicit start() is never capped. |
clock |
() => number |
The manager’s “now” for rules: schedules, cooldowns, snoozes and recorded show times. Default: Date.now. A fake clock previews a campaign or tests rules. |
connect |
boolean |
Connect on creation (see connect()). Default: true. |
TourManager
| Method | Returns | Description |
|---|---|---|
register(tour) |
() => void |
Register a tour (replacing one with the same id). Returns an unregister function, which also removes it from the queue. |
get(id) |
Tour | undefined |
A registered tour. |
getTours() |
Tour[] |
All registered tours. |
start(id, options?) |
Promise<void> |
Start a tour now, or queue it while another tour is on screen. Throws if id isn’t registered. |
explain(id) |
Promise<EligibilityReport> |
Evaluate the tour’s display rules: { eligible, checks: [{ rule, ok, detail }] }. |
startIfEligible(id, options?) |
Promise<boolean> |
Start (or queue) only if the rules allow it. |
signal(name) |
void |
Fire tours whose rules.trigger.signal is name. |
resetImpressions(id?) |
Promise<void> |
Forget shows, outcome and snooze of one tour, or all. |
setRouter(router) |
void |
Set the router on the manager and every registered tour. undefined only resets tours the manager had routed. |
getState() |
TourManagerState |
Immutable snapshot. |
subscribe(listener) |
() => void |
Called when activeId, queue or tourIds change. |
connect() |
() => void |
Start watching: triggers, router, impressions and queue hand-off. Managers connect on creation unless created with connect: false (what TourProvider does, so a render React throws away leaves nothing running). Returns disconnect. |
destroy() |
void |
Unsubscribe from all tours and clear the queue (doesn’t destroy the tours). |
QueueOptions
start(id, options) accepts every StartOptions field (stepId, data, force) plus:
| Option | Type | Default | Description |
|---|---|---|---|
priority |
number |
0 |
Higher runs first. Equal priorities run in the order they were queued. |
interrupt |
boolean |
false |
Start right away, closing (close()) the tour on screen. |
A tour is “on screen” while its status is active or starting. When it finishes (completed, skipped, closed or paused), the highest-priority queued tour starts. Queuing a tour that is already queued replaces its entry.
manager.start('tips', { priority: -1 }); // low priority, runs lastmanager.start('security-alert', { interrupt: true }); // closes whatever is showingTourManagerState
| Field | Type | Description |
|---|---|---|
activeId |
string | null |
Tour currently on screen (active or starting). |
queue |
readonly string[] |
Waiting tours, highest priority first. |
tourIds |
readonly string[] |
Registered tours. |
import { useStoreSelector, useTourManager } from '@awesome-tour/react';
function TourBadge() { const manager = useTourManager(); const { activeId, queue } = useStoreSelector(manager); return <span>{activeId ?? 'idle'} · {queue.length} waiting</span>;}See the multiple tours guide.