A lightweight walkthrough library for React Native utilizing React's Context API
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.
yarn add react-native-walkthrough
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>
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.
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',
},
];
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 fortooltipProps
view thereact-native-walkthrough-tooltip
README