Usage

1. Wrap your app in WalkthroughProvider

WalkthroughProvider is a React context provider. It must wrap everything that contains walkthrough steps, typically the root of your app.

import * as React from "react";
import { WalkthroughProvider } from "rn-interactive-walkthrough";

export default function App() {
  return (
    <WalkthroughProvider>
      <MyAwesomeApp />
    </WalkthroughProvider>
  );
}

2. Define a step

There are two equivalent ways to define a step: the WalkthroughStep component (recommended) or the useWalkthroughStep hook. They accept the same options.

With the WalkthroughStep component

Wrap the view you want to highlight with WalkthroughStep. It measures itself automatically, so you never touch onLayout.

import { WalkthroughStep } from "rn-interactive-walkthrough";
import { NearbyUsersTooltip } from "./Tooltips";

export default function HomeScreen() {
  return (
    <View style={{ flex: 1 }}>
      <WalkthroughStep
        number={1}
        contentComponent={NearbyUsersTooltip}
        style={{ height: 10 }}
      >
        <Text>Here is my app!</Text>
      </WalkthroughStep>
    </View>
  );
}

The component wraps its children in a View and measures that wrapper, so the mask covers exactly the highlighted subtree. Use the style prop to size or position the highlight target when its content doesn't fill a predictable box.

With the useWalkthroughStep hook

Call useWalkthroughStep inside any component, passing the same options, then attach the returned onLayout handler to the View you want to highlight:

import { useWalkthroughStep } from "rn-interactive-walkthrough";
import { NearbyUsersTooltip } from "./Tooltips";

export default function HomeScreen() {
  const { onLayout } = useWalkthroughStep({
    number: 1,
    contentComponent: NearbyUsersTooltip,
  });

  return (
    <View style={{ flex: 1 }}>
      <View style={{ height: 10 }} onLayout={onLayout}>
        <Text>Here is my app!</Text>
      </View>
    </View>
  );
}

Either way, the target is measured so the library knows exactly where to draw the mask (the highlighted area) on the screen. Prefer the component when you highlight a whole subtree; use the hook when you need to attach onLayout to an existing view that already has its own layout, or for a full-screen step.

3. Start the walkthrough

Use the start function from the walkthrough context, e.g. with a button:

import { useWalkthrough } from "rn-interactive-walkthrough";

function StartTourButton() {
  const { start, isReady } = useWalkthrough();

  return (
    <Button
      title="Start the tour"
      disabled={!isReady}
      onPress={start}
    />
  );
}

start begins the walkthrough at the lowest-numbered registered step. isReady becomes true once step 1 has been registered, which is a good condition to check before starting. You can also begin on a specific step by passing its number, e.g. start(3).

4. Navigate steps

Every content component receives the walkthrough context, so next, previous, and goTo are available to move the user through the tour. Extend ContentComponentProps to add your own props, which are passed through contentComponentProps.

import type { ContentComponentProps } from "rn-interactive-walkthrough";

interface NearbyUsersTooltipProps extends ContentComponentProps {
  title: string;
}

const NearbyUsersTooltip = ({ title, ctx }: NearbyUsersTooltipProps) => {
  return (
    <View>
      <Text>{title}</Text>
      <Button title="Back" onPress={ctx.previous} />
      <Button title="Next" onPress={ctx.next} />
    </View>
  );
};

<WalkthroughStep
  number={2}
  contentComponent={NearbyUsersTooltip}
  contentComponentProps={{
    title: "These are all your friends nearby!",
  }}
>
  ...
</WalkthroughStep>

Lifecycle

The walkthrough is a tiny state machine. When it is inactive (no step shown), only start() can begin it; next, previous and goTo do nothing. Once it is active, next, previous and goTo navigate within the tour, while start() is ignored. stop() hides the overlay from either state, returning to inactive.

• next advances one step (stays on the last one). previous goes back one step (stays on the first one). Both no-op while inactive.
• goTo(stepNumber) jumps straight to a step. It only works while active, and is ignored if no registered step has that number.
• start(stepNumber?) begins the tour, at the first step unless a number is given. It is ignored while already active.

isFirstStep and isLastStep tell you where you are in the tour, and are always false while inactive.

See the example app for the full set of patterns.

5. (Optional) Track navigation focus

If your walkthrough spans multiple screens and you use a navigation library, pass a useIsFocused hook to the provider. The walkthrough will automatically stop itself if the user navigates away mid-tour (e.g. via a push notification).

import { WalkthroughProvider } from "rn-interactive-walkthrough";
import { useIsFocused } from "@react-navigation/native";

export default function App() {
  return (
    <WalkthroughProvider useIsFocused={useIsFocused}>
      <MyAwesomeApp />
    </WalkthroughProvider>
  );
}