Router Integration

npm install @tour-kit/react

'use client'

import { TourKitProvider, TourProvider, useNextAppRouter } from '@tour-kit/react'

export function Providers({ children }) {
  const router = useNextAppRouter()

  return (
    <TourKitProvider>
      <TourProvider tours={tours} router={router}>
        {children}
      </TourProvider>
    </TourKitProvider>
  )
}

import { createTour, createStep } from '@tour-kit/core'

export const onboardingTour = createTour({
  id: 'onboarding',
  steps: [
    createStep({
      id: 'welcome',
      target: '#welcome-banner',
      route: '/', // Step requires this route
      content: {
        title: 'Welcome!',
        description: 'Let\'s explore your dashboard.',
      },
    }),
    createStep({
      id: 'settings',
      target: '#settings-panel',
      route: '/settings', // Automatically navigates here
      content: {
        title: 'Settings',
        description: 'Customize your experience.',
      },
    }),
    createStep({
      id: 'profile',
      target: '#profile-form',
      route: '/settings/profile',
      content: {
        title: 'Your Profile',
        description: 'Complete your profile to get started.',
      },
    }),
  ],
})

import { TourKitProvider, TourProvider, useNextPagesRouter } from '@tour-kit/react'

function MyApp({ Component, pageProps }) {
  const router = useNextPagesRouter()

  return (
    <TourKitProvider>
      <TourProvider tours={tours} router={router}>
        <Component {...pageProps} />
      </TourProvider>
    </TourKitProvider>
  )
}

export default MyApp

import { BrowserRouter } from 'react-router-dom'
import { TourKitProvider, TourProvider, useReactRouter } from '@tour-kit/react'

function AppProviders({ children }) {
  const router = useReactRouter()

  return (
    <TourKitProvider>
      <TourProvider tours={tours} router={router}>
        {children}
      </TourProvider>
    </TourKitProvider>
  )
}

function App() {
  return (
    <BrowserRouter>
      <AppProviders>
        <Routes>
          {/* Your routes */}
        </Routes>
      </AppProviders>
    </BrowserRouter>
  )
}

interface RouterAdapter {
  // Get the current route path
  getCurrentRoute(): string

  // Navigate to a route (can be async)
  navigate(route: string): void | Promise<boolean | undefined>

  // Check if current route matches a pattern
  matchRoute(
    pattern: string,
    mode?: 'exact' | 'startsWith' | 'contains'
  ): boolean

  // Subscribe to route changes
  onRouteChange(callback: (route: string) => void): () => void
}

import { useCallback, useEffect, useRef } from 'react'
import type { RouterAdapter } from '@tour-kit/core'

export function useMyRouter(): RouterAdapter {
  const pathnameRef = useRef(window.location.pathname)
  const callbacksRef = useRef(new Set<(route: string) => void>())

  // Update ref when pathname changes
  useEffect(() => {
    const handlePopState = () => {
      const newPath = window.location.pathname
      pathnameRef.current = newPath
      callbacksRef.current.forEach(cb => cb(newPath))
    }

    window.addEventListener('popstate', handlePopState)
    return () => window.removeEventListener('popstate', handlePopState)
  }, [])

  const getCurrentRoute = useCallback(() => pathnameRef.current, [])

  const navigate = useCallback((route: string) => {
    window.history.pushState({}, '', route)
    pathnameRef.current = route
    callbacksRef.current.forEach(cb => cb(route))
  }, [])

  const matchRoute = useCallback((pattern: string, mode = 'exact') => {
    const current = pathnameRef.current
    switch (mode) {
      case 'startsWith': return current.startsWith(pattern)
      case 'contains': return current.includes(pattern)
      default: return current === pattern
    }
  }, [])

  const onRouteChange = useCallback((callback: (route: string) => void) => {
    // Call immediately with current route
    callback(pathnameRef.current)
    callbacksRef.current.add(callback)
    return () => callbacksRef.current.delete(callback)
  }, [])

  return { getCurrentRoute, navigate, matchRoute, onRouteChange }
}

createStep({
  id: 'settings-step',
  target: '#settings',
  route: '/settings', // Uses exact match by default
  routeMatchMode: 'startsWith', // Match any /settings/* route
})

const tour = createTour({
  id: 'multi-page',
  steps: [
    { id: 'step-1', route: '/page-a', target: '#element-a' },
    { id: 'step-2', route: '/page-b', target: '#element-b' }, // Auto-navigates
  ],
})

createStep({
  id: 'settings-step',
  target: '#settings',
  route: '/settings',
  // Default — set to 'prompt' or 'manual' to opt out.
  routeChangeStrategy: 'auto',
})

import { TourProvider, type TourRouteError } from '@tour-kit/core'

<TourProvider
  tours={tours}
  router={router}
  onStepError={(err: TourRouteError) => {
    if (err.code === 'TARGET_NOT_FOUND') {
      analytics.track('tour_step_target_missing', {
        route: err.route,
        selector: err.selector,
      })
    }
  }}
/>

<TourProvider
  tours={tours}
  router={router}
  onBeforeNavigate={(route, step) => {
    // Return false to prevent navigation
    if (hasUnsavedChanges()) {
      return confirm('Leave without saving?')
    }
    return true
  }}
  onAfterNavigate={(route, step) => {
    analytics.track('tour_navigated', { route, stepId: step.id })
  }}
/>

<TourKitProvider
  persistence={{
    enabled: true,
    storage: 'localStorage',
    prefix: 'my-app-tours',
  }}
>

const { resumeLastTour } = useTour()

useEffect(() => {
  // Check if there's a tour to resume
  resumeLastTour()
}, [])

createStep({
  id: 'dynamic-step',
  route: '/dashboard',
  target: '#dynamic-widget',
  waitForTarget: true, // Wait up to 5 seconds for element
  waitForTargetTimeout: 5000,
})

const onRouteChange = (callback) => {
  // Important: Call immediately!
  callback(getCurrentRoute())

  // Then subscribe to changes
  return subscribe(callback)
}

const navigate = (route) => {
  console.log('Navigating to:', route)
  router.push(route) // Make sure this works
}