TourProvider
App-level provider that coordinates several tours, shares a router adapter and the anchor registry.
TourProvider is optional. A single Tour.Root with a tour works without it. Add the provider when you need any of these:
- Several tours. Only one is on screen at a time; the others wait in a priority queue (see Multiple tours).
- Tours by id.
Tour.Root tourId,useTour('id'), checklist items withtour: 'id', and devtools all look tours up on the provider. - Multi-page tours. One router adapter is shared by every tour (see Multi-page tours).
- A scoped anchor registry. For tests, micro-frontends, or several apps on one page.
import { TourProvider } from '@awesome-tour/react';
<TourProvider tours={[onboarding, whatsNew]} router={router}> <App /></TourProvider>;Props
| Prop | Type | Default | Description |
|---|---|---|---|
tours |
TourInstance[] |
— | Tours to register. They are registered on the first render, so children can look them up right away. |
router |
RouterAdapter |
— | Router adapter set on every registered tour. |
preview |
{ load, param?, stepParam?, onError? } |
— | Run a draft named in the URL (?tour-preview=id) without saving or tracking anything. See Previewing drafts. |
locale / fallbackLocale |
string |
<html lang> / 'en' |
Locale for step text given per locale. See i18n. |
deepLink |
boolean | DeepLinkOptions |
— | Start the tour named in the URL (?tour=id&step=x) once it’s registered, then clean the URL. Options rename the parameters (param, stepParam) or keep them (clean: false). |
anchors |
AnchorRegistry |
the global registry | Registry used by useTourAnchor, Tour.Anchor, hotspots, inline tours and TourTarget3D. |
manager |
TourManager |
created internally | Bring your own manager, for example one created outside React with createTourManager. |
How things flow through context
-
Tours. These tours register on the provider’s manager:
- tours passed to
tours; - tours rendered by a
Tour.Rootgiven atourprop; - inline
Tour.Roottours.
Tour.Root tourId="…"only looks a tour up and does not register it. A tour leaves the manager when its root unmounts or when it is removed fromtours. - tours passed to
-
Starting.
Tour.Trigger,Tour.Rootopen/defaultOpen, andChecklist.ItemTriggerstart registered tours throughmanager.start(). If another tour is on screen, the new one is queued instead of overlapping. Callingtour.start()directly bypasses the queue. -
Router. When the provider has a
router, the manager callstour.setRouter(router)on every tour it registers, and again whenever the prop changes. Without one, tours keep therouterthey were created with. -
Anchors.
useTourAnchorandTour.Anchorregister elements in the provider’s registry. Inline tours created byTour.Rootresolveanchor(id)against that same registry. Tours created withcreateTouruse their ownanchorsoption, which defaults to the global registry, so they match the provider unless you pass a custom registry to both.
useTourProvider
function useTourProvider(): { manager: TourManager; anchors: AnchorRegistry } | null;Returns the nearest provider’s value, or null outside a provider. Library code uses it to work with or without a provider.
useTourManager
function useTourManager(): TourManager;Returns the provider’s manager. Throws outside a TourProvider. Read its state with useStoreSelector:
function ActiveTourBadge() { const manager = useTourManager(); const { activeId, queue } = useStoreSelector(manager); return activeId ? <span>{activeId} (+{queue.length} queued)</span> : null;}
// Queue a tour with a priority, or interrupt the active one:manager.start('whats-new', { priority: 10 });manager.start('critical-update', { interrupt: true });TourContext
TourContext is the React context provided by each Tour.Root. useTourContext(componentName?) reads it and throws outside a root. It’s meant for building your own parts. The value contains:
tour,state,step, andopen(whether the tour UI should be on screen).modal,interactive,dir,keyboardNavigation,closeOnEscapeandcloseOnOverlayClick.contentId, the id ofTour.Content.registerLayer, to keep custom layers interactive under a modal tour. You will usually useuseTourLayerinstead.
import { useTourContext } from '@awesome-tour/react';
function StepBadge() { const { state, open } = useTourContext('StepBadge'); return open ? <span data-step={state.stepId}>{state.progress.current}</span> : null;}For most needs, prefer the higher-level hooks: useTourState, useTourStep and useTour.