Skip to content
awesome-tour

Type to search every page.

    ETour managerContents

    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 finishes

    In 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 last
    manager.start('security-alert', { interrupt: true }); // closes whatever is showing

    TourManagerState

    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.