Router Adapters

Router adapters enable multi-page product tours that persist across route changes in React framework applications

Router adapters connect userTourKit to your application's routing system, enabling multi-page tours that navigate users across different routes.

Why Use Router Adapters?

Multi-page tours need to:

Navigate between pages - Automatically go to the correct route for each step
Detect route changes - Know when users navigate away from a step's route
Match routes flexibly - Support exact, prefix, and contains matching
Persist state - Remember progress across page loads

Available Adapters

Next.js App Router

For Next.js 13+ App Router with next/navigation

Next.js Pages Router

For Next.js Pages Router with next/router

React Router

For React Router v6/v7 in SPAs

Two Usage Patterns

Each adapter provides two ways to create it:

1. Direct Hook (Recommended)

Simple to use - automatically imports the router library:

import { useNextAppRouter } from '@tour-kit/react';

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

  return (
    <MultiTourKitProvider router={router}>
      {/* ... */}
    </MultiTourKitProvider>
  );
}

2. Factory Function

For custom setups or when you need more control:

import { createNextAppRouterAdapter } from '@tour-kit/react';
import { usePathname, useRouter } from 'next/navigation';

const useMyRouter = createNextAppRouterAdapter(usePathname, useRouter);

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

  return (
    <MultiTourKitProvider router={router}>
      {/* ... */}
    </MultiTourKitProvider>
  );
}

RouterAdapter Interface

All adapters implement this interface:

Prop

Type

Route Matching Modes

<TourStep
  route="/dashboard"
  routeMatch="exact"      // Only "/dashboard"
/>

<TourStep
  route="/dashboard"
  routeMatch="startsWith" // "/dashboard", "/dashboard/settings", etc.
/>

<TourStep
  route="/settings"
  routeMatch="contains"   // "/app/settings", "/user/settings", etc.
/>

Custom Adapter

Create your own adapter for other routing libraries:

import type { RouterAdapter } from '@tour-kit/core';

function useMyCustomRouter(): RouterAdapter {
  const location = useYourRouterLocation();
  const navigate = useYourRouterNavigate();
  const callbacksRef = useRef<Set<(route: string) => void>>(new Set());

  useEffect(() => {
    // Notify on route change
    for (const cb of callbacksRef.current) {
      cb(location.pathname);
    }
  }, [location.pathname]);

  return {
    getCurrentRoute: () => location.pathname,

    navigate: (route: string) => {
      navigate(route);
    },

    matchRoute: (pattern, mode = 'exact') => {
      const current = location.pathname;
      switch (mode) {
        case 'exact': return current === pattern;
        case 'startsWith': return current.startsWith(pattern);
        case 'contains': return current.includes(pattern);
      }
    },

    onRouteChange: (callback) => {
      callbacksRef.current.add(callback);
      callback(location.pathname); // Initial call
      return () => callbacksRef.current.delete(callback);
    },
  };
}

Usage with MultiTourKitProvider

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

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

  return (
    <MultiTourKitProvider
      router={router}
      routePersistence={{ enabled: true }}
      autoNavigate={true}
    >
      <Tour id="onboarding">
        <TourStep
          target="#home"
          title="Home"
          route="/"
          routeMatch="exact"
        />
        <TourStep
          target="#dashboard"
          title="Dashboard"
          route="/dashboard"
          routeMatch="startsWith"
        />
      </Tour>
      <TourOverlay />
      <TourCard />
      <Routes />
    </MultiTourKitProvider>
  );
}

Next.js Integration - Complete Next.js setup guide
Vite Integration - Vite with React Router setup
Router Integration Guide - Deep dive into multi-page tours

Router Adapters

Next.js App Router

Next.js Pages Router

React Router

On this page