Migrating

If you are here because a tour library misbehaves on the New Architecture, that is the common thread: react-native-copilot, rn-tourguide, and react-native-spotlight-tour were built for the old architecture and have struggled since Fabric became the default - two have had no release since late 2024, and the third has open, unresolved rendering bugs. Guideway started on Fabric.

The mental model is similar across all three, so migration is mostly mechanical.

The mapping

What you had	In Guideway
Wrapping components in a HOC / walkthroughable / AttachStep	A ref from useTourTarget(id) on the target view
Steps defined as components or props scattered across the tree	A tour as plain data: { id, steps: [{ id, title, body }] }
A start() / start(stepNumber) call	useTour().start(tourId)
next / prev / stop handlers	useTour() -> next, back, skip, stop
Custom tooltip component prop	tooltipComponent (global) or a step’s render
Library-specific theming props	colorScheme + theme tokens

General steps

1. Install Guideway and its peers (see Installation).
2. Wrap your app in a single TourProvider, passing insets from useSafeAreaInsets().
3. Replace each highlighted element’s wrapper with a ref: const ref = useTourTarget('step-id') and <View ref={ref} />.
4. Move your step definitions into a tours array, keying each step’s id to the matching useTourTarget id.
5. Replace the old start/next/stop calls with the useTour() controller.

From react-native-copilot

Copilot uses copilot() HOCs and walkthroughable wrappers. Drop the HOC; mark targets with useTourTarget. Copilot’s CopilotStep name/order become a step id and array position. start() becomes start(tourId).

Detailed mapping, comparison table, and code: Guideway vs react-native-copilot.

From rn-tourguide

Replace TourGuideProvider with TourProvider, and TourGuideZone wrappers with a useTourTarget ref on the same view. The zone number maps to the step’s array position; give each a stable id.

Detailed mapping, comparison table, and code: Guideway vs rn-tourguide.

From react-native-spotlight-tour

Spotlight-tour is the closest in spirit (spotlight + steps). Replace its SpotlightTourProvider and AttachStep with TourProvider and useTourTarget. Its per-step shape maps to Guideway’s cutout.shape (rect / rounded / circle / pill).

Detailed mapping, comparison table, and code: Guideway vs react-native-spotlight-tour.

Once migrated you also get what those libraries lack on Fabric: auto-scroll, FlatList support, built-in theming, and show-once persistence.