MultiTourKitProvider

MultiTourKitProvider: manage multiple independent tours with shared configuration, analytics, and storage settings

The top-level provider for userTourKit that manages multiple tours, routing, persistence, and lifecycle callbacks.

Why Use This Provider?

Multi-tour registry - Register and manage multiple tours declaratively
Shared configuration - Apply global settings to all tours
Router integration - Connect to your app's routing system
Lifecycle callbacks - Track tour starts, completions, and step views
State persistence - Preserve tour progress across navigations

Basic Usage

import {
  MultiTourKitProvider,
  Tour,
  TourStep,
  TourOverlay,
  TourCard,
} from '@tour-kit/react';

function App() {
  return (
    <MultiTourKitProvider>
      <Tour id="welcome">
        <TourStep target="#hero" title="Welcome!" content="..." />
      </Tour>

      <TourOverlay />
      <TourCard />

      <YourApp />
    </MultiTourKitProvider>
  );
}

Props

Prop

Type

With Router Integration

import {
  MultiTourKitProvider,
  useNextAppRouter,
  Tour,
  TourStep,
} from '@tour-kit/react';

function App() {
  const router = useNextAppRouter();

  return (
    <MultiTourKitProvider
      router={router}
      routePersistence={{
        enabled: true,
        storage: 'localStorage',
        expiryMs: 24 * 60 * 60 * 1000, // 24 hours
        syncTabs: true,
      }}
      autoNavigate={true}
    >
      <Tour id="onboarding">
        <TourStep target="#home" title="Home" route="/" />
        <TourStep target="#dashboard" title="Dashboard" route="/dashboard" />
      </Tour>

      <TourOverlay />
      <TourCard />
    </MultiTourKitProvider>
  );
}

Lifecycle Callbacks

Track tour analytics with lifecycle callbacks:

<MultiTourKitProvider
  onTourStart={(tourId) => {
    analytics.track('tour_started', { tourId });
  }}
  onTourComplete={(tourId) => {
    analytics.track('tour_completed', { tourId });
  }}
  onTourSkip={(tourId, stepIndex) => {
    analytics.track('tour_skipped', { tourId, stoppedAt: stepIndex });
  }}
  onStepView={(tourId, stepId, stepIndex) => {
    analytics.track('step_viewed', { tourId, stepId, stepIndex });
  }}
>

Multiple Tours

<MultiTourKitProvider>
  <Tour id="welcome">
    <TourStep target="#hero" title="Welcome!" />
    <TourStep target="#features" title="Features" />
  </Tour>

  <Tour id="feature-deep-dive">
    <TourStep target="#feature-1" title="Feature 1" />
    <TourStep target="#feature-2" title="Feature 2" />
    <TourStep target="#feature-3" title="Feature 3" />
  </Tour>

  <TourOverlay />
  <TourCard />
</MultiTourKitProvider>

Start specific tours:

function TourButtons() {
  const { start } = useTour();

  return (
    <>
      <button onClick={() => start('welcome')}>Start Welcome Tour</button>
      <button onClick={() => start('feature-deep-dive')}>Deep Dive</button>
    </>
  );
}

Global Configuration

Apply settings to all tours:

<MultiTourKitProvider
  config={{
    defaultPlacement: 'bottom',
    spotlight: {
      enabled: true,
      padding: 8,
      borderRadius: 8,
    },
    keyboard: {
      enabled: true,
      escapeCloses: true,
      arrowNavigation: true,
    },
    a11y: {
      announceSteps: true,
      politeness: 'polite',
    },
    scroll: {
      enabled: true,
      behavior: 'smooth',
      block: 'center',
    },
  }}
>

TourKitConfig Options

Prop

Type

Route Persistence Configuration

Prop

Type

Disable auto-navigation and handle it yourself:

<MultiTourKitProvider
  router={router}
  autoNavigate={false}
  onNavigationRequired={(route, stepId) => {
    // Show confirmation dialog
    if (confirm(`Navigate to ${route}?`)) {
      router.navigate(route);
    }
  }}
>

Architecture

The provider composes three internal providers:

<TourRegistryContext.Provider>    {/* Tour registration */}
  <CoreTourKitProvider>            {/* Global config, callbacks */}
    <TourProvider>                  {/* Tour state, routing */}
      {children}
    </TourProvider>
  </CoreTourKitProvider>
</TourRegistryContext.Provider>

Tour - Individual tour component
useTours - Access all registered tours
Router Adapters - Router integration options

MultiTourKitProvider

Why Use This Provider?

Basic Usage

Props

With Router Integration

Lifecycle Callbacks

Multiple Tours

Global Configuration

TourKitConfig Options

Route Persistence Configuration

Manual Navigation Control

Architecture

On this page