React Native Walkthrough

Walkthrough

NOTE: This library is currently under development, and should primarly be considered as being in a beta stage.

React Native Walkthrough is an app-wide walkthrough library, with a minimal footprint.

Installation

yarn add react-native-walkthrough

Roadmap

• [ ] Move library to Typescript (soon!)
• [ ] add ability to pass external EventEmitter instance via props
• [ ] add props for changing timeout durations
• [ ] ???

Basic Usage

React Native Walkthrough exports the following:

• WalkthroughProvider component
• WalkthroughElement component
• startWalkthrough function
• dispatchWalkthroughEvent function
• goToWalkthroughElementWithId function

WalkthroughProvider

First, you will need to wrap your entire app in the WalkthroughProvider component (no props or additional config required)

import { WalkthroughProvider } from 'react-native-walkthrough';

render() {
  return (
    <WalkthroughProvider>
      <YourAppHere />
    </WalkthroughProvider>
  )  
}

WalkthroughElement

When you wish to highlight something as a part of a Walkthrough, you simply wrap the component in a WalkthroughElement and give it a unique id.

import { WalkthroughElement } from 'react-native-walkthrough';

<WalkthroughElement id="profile-button">   // just add this!
  <TouchableOpacity
    style={styles.profileButton}
    onPress={() => navigate('Profile', {name: 'Jane'})}
  >
    <Text>{"Go to Jane's profile"}</Text>
  </TouchableOpacity>
</WalkthroughElement>

This library utilizes react-native-walkthrough-tooltip to render the content bubbles that point to a WalkthroughElement. You can edit the content of the tooltip in the walkthrough guide, or by providing the optional content prop directly on the WalkthroughElement component.

startWalkthrough

Function that accepts a walkthrough guide array and begins the walkthrough by setting the current element as the first element from the walkthrough guide array. Learn about walkthrough guides here

import { startWalkthrough } from 'react-native-walkthrough';

import profileWalkthrough from '../guides/profileWalkthrough';

<TouchableOpacity
  onPress={() => startWalkthrough(profileWalkthrough)}
>
  <Text>{"Show me how to view a profile"}</Text>
</TouchableOpacity>

dispatchWalkthroughEvent

Function that accepts a string event name. Walkthrough events are used to wait-then-show the next element in a walkthrough. Add a triggerEvent to the walkthrough element in a guide, then be sure to dispatch the walkthrough event when it occurs to trigger the tooltip to be displayed.

import { NavigationEvents } from 'react-navigation';
import { dispatchWalkthroughEvent } from 'react-native-walkthrough';

render (
  <React.Fragment>
    <NavigationEvents
      onDidFocus={() => dispatchWalkthroughEvent('profile-focus')}
    />
    ...
  </React.Fragment>
)

goToWalkthroughElementWithId

Function that accepts a string element id. Finds the first element in the current walkthrough with a matching id and sets that element as the current element.

import { goToWalkthroughElementWithId } from 'react-native-walkthrough';


<TouchableOpacity
  onPress={() => goToWalkthroughElementWithId('step-3')}
>
  <Text>{"Skip to next step"}</Text>
</TouchableOpacity>

Creating a Walkthrough Guide

A walkthrough guide is simply an array of objects, where each object correlates to a WalkthroughElement. Each element object in the guide must have an id and content to display in the tooltip bubble.

Example guide

import React from 'react';
import {View, Text, StyleSheet} from 'react-native';

const styles = StyleSheet.create({
  tooltipView: {
    paddingHorizontal: 24,
    paddingVertical: 8,
  },
  tooltipText: {
    color: 'black',
    fontSize: 18,
  },
});

const makeTooltipContent = text => (
  <View style={styles.tooltipView}>
    <Text style={styles.tooltipText}>{text}</Text>
  </View>
);

export default [
  {
    id: 'profile-button',
    content: makeTooltipContent('Tap here to view a profile'),
  },
  {
    id: 'profile-name',
    content: makeTooltipContent("Here is the user's name"),
    placement: 'bottom',
    triggerEvent: 'profile-focus',
  },
];

Guide values

|Key|Type|Required|Description| |---|----|-----|----| |content|function/Element| YES | This is the view displayed in the tooltip popover bubble | |id|string|YES|id string that matches the corresponding WalkthroughElement| |placement|string|NO | Determines placement of tooltip in relation to the element it is wrapping |possibleOutcomes|array|NO|An array of objects with keys (event, action) that creates event listeners for multiple events to provide the ability to have an outcome tree that responds to a user's actions (listens to events dispatched via dispatchWalkthroughEvent| |tooltipProps|object|NO|additional props to customize the tooltip functionality and style |triggerEvent|string|NO|string event id, this element will not appear until the triggerEvent is dispatched via dispatchWalkthroughEvent

To learn more about placement options and all the options for tooltipProps view the react-native-walkthrough-tooltip README