react-native-quick-walkthrough

A React Native walkthrough library built for modern navigation — steps survive screen transitions, refs unregister on unmount, and the engine navigates itself so tours can span multiple routes.

Why This Exists

Existing walkthrough libraries (e.g. react-native-copilot) assume all tour steps are mounted at the same time. This breaks with Expo Router and React Navigation v7 because refs die when screens unmount. react-native-quick-walkthrough solves this: each step declares its route, the engine navigates there, and the registry waits for the ref before measuring.

Architecture

Consumer App
  │
  ├── <TourProvider>              ← injects adapters, renders TourOverlay as sibling of children
  │   │
  │   ├── <TourTarget id="a">    ← registers ref on mount, unregisters on unmount
  │   │     {children}
  │   │
  │   └── <TourTarget id="b">
  │         {children}
  │
  └── <TourOverlay>  (sibling View, same container as targets)
        ├── <Spotlight>           ← 4 dark edge strips + 4 rounded corners, UI-thread Reanimated
        └── <Tooltip>             ← auto-positioned via utils/positioning.ts

Engine per step:
  navigate (if route differs)
    → registry.waitFor(targetId, 3000ms)
      → requestAnimationFrame
        → measureInWindow
          → animate Spotlight → show Tooltip

State: Zustand store — selective subscriptions, no re-renders during 60fps animations
Adapters: NavigationAdapter + PersistenceAdapter (both injected by consumer)

Installation

# npm
npm install react-native-quick-walkthrough

# yarn
yarn add react-native-quick-walkthrough

Peer Dependencies

yarn add react-native-reanimated react-native-safe-area-context

For Expo Router:

# expo-router is already installed in Expo projects — no extra step needed

Follow the platform setup guide for react-native-reanimated before proceeding.

Quickstart

1. Define a Tour

Define tours once, outside any component. Each step knows its route and target.

// tours/onboarding.ts
import { defineTour } from 'react-native-quick-walkthrough';

export const onboardingTour = defineTour({
  id: 'onboarding',
  steps: [
    {
      id: 'welcome',
      route: '/(tabs)/',
      target: 'home-button',
      text: 'This is your home screen. Tap here to get started.',
    },
    {
      id: 'profile',
      route: '/(tabs)/profile',
      target: 'profile-avatar',
      text: 'Tap your avatar to edit your profile.',
    },
  ],
});

2. Wrap Your App in TourProvider

createExpoRouterAdapter() returns { adapter, Bridge }. Pass adapter to TourProvider and render <Bridge /> inside it so the adapter receives route changes via usePathname().

// app/_layout.tsx
import {
  TourProvider,
  createExpoRouterAdapter,
} from 'react-native-quick-walkthrough';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { onboardingTour } from '../tours/onboarding';

const { adapter, Bridge } = createExpoRouterAdapter();

const persistence = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key),
};

export default function RootLayout() {
  return (
    <TourProvider
      tours={[onboardingTour]}
      navigationAdapter={adapter}
      persistence={persistence} // optional
    >
      <Bridge />
      <Stack />
    </TourProvider>
  );
}

3. Mark Tour Targets

Wrap any element you want to highlight with TourTarget. The id must match a step's target field.

// app/(tabs)/index.tsx
import { TourTarget } from 'react-native-quick-walkthrough';

export default function HomeScreen() {
  return (
    <View>
      <TourTarget id="home-button">
        <Pressable onPress={...}>
          <Text>Get Started</Text>
        </Pressable>
      </TourTarget>
    </View>
  );
}

4. Start the Tour

import { useTour } from 'react-native-quick-walkthrough';

export default function HomeScreen() {
  const { start } = useTour();

  return <Button title="Start tour" onPress={() => start('onboarding')} />;
}

start takes the tour id (string). The tour object itself is registered via TourProvider's tours prop.

Configuration

NavigationAdapter

| Adapter | Import | Notes | | ----------- | --------------------------- | --------------------------------------------------------------------------------------------------- | | Expo Router | createExpoRouterAdapter() | Returns { adapter, Bridge }. Pass adapter to TourProvider and render <Bridge /> as a child. |

React Navigation adapter is not yet shipped.

TourProvider props

| Prop | Type | Required | Description | | --------------------- | -------------------- | -------- | ---------------------------------------------------- | | tours | Tour[] | yes | All tours the consumer wants to start by id | | navigationAdapter | NavigationAdapter | yes | Navigation adapter (e.g. adapter from Expo Router) | | persistence | PersistenceAdapter | no | Key-value store for completion state | | tapOutsideToAdvance | boolean | no | Tap outside spotlight to advance | | blockOutsideTouches | boolean | no | Block touches outside the spotlight hole |

PersistenceAdapter

Pass any key-value store that implements { get, set, remove }. If omitted, completed tours reset on every app restart.

| Storage | Package | | ------------ | ------------------------------------------- | | AsyncStorage | @react-native-async-storage/async-storage | | MMKV | react-native-mmkv | | In-memory | Custom implementation |

useTour

const {
  start,
  stop,
  next,
  prev,
  skip,
  status,
  currentStepIndex,
  activeTour,
  isRunning,
} = useTour();

| Member | Type | Description | | ------------------ | ------------------------------- | ------------------------------------------------ | | start(id) | (id: TourId) => Promise<void> | Begin a tour by id from step 0 | | stop() | () => void | Abort the current tour | | next() | () => void | Advance to next step | | prev() | () => void | Go back to previous step | | skip() | () => void | Skip remaining steps (fires onSkip) | | status | TourStatus | 'idle' \| 'running' \| 'paused' \| 'completed' | | currentStepIndex | number | Active step index | | activeTour | Tour \| null | Active tour object | | isRunning | boolean | Shortcut for status === 'running' |

Compatibility

| React Native | Expo SDK | New Architecture | Tested Platforms | | ------------ | -------- | ------------------ | ----------------- | | ≥ 0.73 | ≥ 50 | Supported (Fabric) | iOS, Android, Web |

Troubleshooting

Target not found (timeout after 3s)

The engine waited 3 seconds for a target ref to appear but it never registered. Check that:

• The id in defineTour matches the id prop on <TourTarget> exactly (case-sensitive)
• The route in the step matches the actual Expo Router route string (check with router.pathname)
• The TourTarget is mounted on the screen it belongs to, not conditionally hidden

Spotlight flickers or misaligns on Android

Android collapses view hierarchies by default. Add collapsable={false} to any View that wraps a TourTarget:

<View collapsable={false}>
  <TourTarget id="...">...</TourTarget>
</View>

TourTarget sets this automatically on its own wrapper, but parent views can still interfere.

Tour does not persist between sessions

No persistence adapter was passed to TourProvider. Pass an AsyncStorage or MMKV adapter to enable persistence.

Contributing

See CONTRIBUTING.md. All contributions require a DCO sign-off.

Security

See SECURITY.md for the vulnerability reporting process. Do not open public issues for security bugs.

License

MIT — Copyright (c) 2026 Carlos Cao. See LICENSE.