Core concepts

Guideway has a small surface area built on three ideas.

Tours are data

A tour is a plain object: an id and an array of steps. No JSX, no special components - you can keep tours in a file, fetch them, or build them at runtime.

const tours = [
  {
    id: 'main',
    steps: [
      { id: 'search', title: 'Find anything', body: 'Search from here.' },
      { id: 'create', title: 'Create', body: 'Tap + to start.' },
    ],
    onComplete: () => console.log('done'),
  },
];

Each step has an id, optional title / body, and optional placement and cutout. A tour can set showOnce (see Persistence) and onComplete / onSkip callbacks.

Targets are refs

A step highlights a view. You connect the two by id: call useTourTarget('search'), which returns a ref, and attach that ref to the view.

const ref = useTourTarget('search');
<TextInput ref={ref} />

When a step becomes active, Guideway measures that ref’s view on screen and draws the spotlight around it. If the target lives in a scroll container, Guideway can scroll it into view first - see Auto-scroll.

One provider drives everything

TourProvider holds the registered tours and the running state, and renders the overlay in place (not a Modal), so it sits correctly within your navigation. Any component inside it can reach the controller with useTour():

const { start, next, back, skip, isActive } = useTour();
start('main');

The lifecycle of a step:

1. start(tourId) activates the tour at step 0.
2. Guideway looks up the step’s target ref and measures it (scrolling it into view if needed).
3. The Reanimated spotlight animates to the target and the tooltip appears.
4. next / back / skip (or a scrim tap) move through the tour; the keyboard is dismissed on every change.

That is the whole model. Everything else - theming, placement, interaction, persistence - is configuration on top of it.