RN-TourGuide

A flexible tourguide for your react native app!
🎉 Webable 🎉
(a rewriting of react-native-copilot)

🎉DEMO WEB 🎉

Installation

yarn add rn-tourguide

yarn add react-native-svg
react-native link react-native-svg

If you are using Expo:

expo install react-native-svg

Usage

1import {
2  TourGuideProvider, // Main provider
3  TourGuideZone, // Main wrapper of highlight component
4  TourGuideZoneByPosition, // Component to use mask on overlay (ie, position absolute)
5  useTourGuideController, // hook to start, etc.
6} from 'rn-tourguide'
7
8// Add <TourGuideProvider/> at the root of you app!
9function App() {
10  return (
11// If you added a statusbar in Andoid set androidStatusBarVisible: true as well to avoid vertical position issues
12    <TourGuideProvider {...{ borderRadius: 16 }}>
13      <AppContent />
14    </TourGuideProvider>
15  )
16}
17
18const AppContent = () => {
19  const iconProps = { size: 40, color: '#888' }
20
21  // Use Hooks to control!
22  const {
23    canStart, // a boolean indicate if you can start tour guide
24    start, // a function to start the tourguide
25    stop, // a function  to stopping it
26    eventEmitter, // an object for listening some events
27  } = useTourGuideController()
28
29  // Can start at mount 🎉
30  // you need to wait until everything is registered 😁
31  React.useEffect(() => {
32    if (canStart) {
33      // 👈 test if you can start otherwise nothing will happen
34      start()
35    }
36  }, [canStart]) // 👈 don't miss it!
37
38  const handleOnStart = () => console.log('start')
39  const handleOnStop = () => console.log('stop')
40  const handleOnStepChange = () => console.log(`stepChange`)
41
42  React.useEffect(() => {
43    eventEmitter.on('start', handleOnStart)
44    eventEmitter.on('stop', handleOnStop)
45    eventEmitter.on('stepChange', handleOnStepChange)
46
47    return () => {
48      eventEmitter.off('start', handleOnStart)
49      eventEmitter.off('stop', handleOnStop)
50      eventEmitter.off('stepChange', handleOnStepChange)
51    }
52  }, [])
53
54  return (
55    <View style={styles.container}>
56      {/*
57
58          Use TourGuideZone only to wrap your component
59
60      */}
61      <TourGuideZone
62        zone={2}
63        text={'A react-native-copilot remastered! 🎉'}
64        borderRadius={16}
65      >
66        <Text style={styles.title}>
67          {'Welcome to the demo of\n"rn-tourguide"'}
68        </Text>
69      </TourGuideZone>
70      <View style={styles.middleView}>
71        <TouchableOpacity style={styles.button} onPress={() => start()}>
72          <Text style={styles.buttonText}>START THE TUTORIAL!</Text>
73        </TouchableOpacity>
74
75        <TourGuideZone zone={3} shape={'rectangle_and_keep'}>
76          <TouchableOpacity style={styles.button} onPress={() => start(4)}>
77            <Text style={styles.buttonText}>Step 4</Text>
78          </TouchableOpacity>
79        </TourGuideZone>
80        <TouchableOpacity style={styles.button} onPress={() => start(2)}>
81          <Text style={styles.buttonText}>Step 2</Text>
82        </TouchableOpacity>
83        <TouchableOpacity style={styles.button} onPress={stop}>
84          <Text style={styles.buttonText}>Stop</Text>
85        </TouchableOpacity>
86        <TourGuideZone
87          zone={1}
88          shape='circle'
89          text={'With animated SVG morphing with awesome flubber 🍮💯'}
90        >
91          <Image source={{ uri }} style={styles.profilePhoto} />
92        </TourGuideZone>
93      </View>
94      <View style={styles.row}>
95        <TourGuideZone zone={4} shape={'circle'}>
96          <Ionicons name='ios-contact' {...iconProps} />
97        </TourGuideZone>
98        <Ionicons name='ios-chatbubbles' {...iconProps} />
99        <Ionicons name='ios-globe' {...iconProps} />
100        <TourGuideZone zone={5}>
101          <Ionicons name='ios-navigate' {...iconProps} />
102        </TourGuideZone>
103        <TourGuideZone zone={6} shape={'circle'}>
104          <Ionicons name='ios-rainy' {...iconProps} />
105        </TourGuideZone>
106        <TourGuideZoneByPosition
107          zone={7}
108          shape={'circle'}
109          isTourGuide
110          bottom={30}
111          left={35}
112          width={300}
113          height={300}
114        />
115      </View>
116    </View>
117  )
118}

TourGuide props:

1interface TourGuideZoneProps {
2  zone: number // A positive number indicating the order of the step in the entire walkthrough.
3  tourKey?: string // A string indicating which tour the zone belongs to
4  isTourGuide?: boolean // return children without wrapping id false
5  text?: string // text in tooltip
6  shape?: Shape // which shape
7  maskOffset?: number // offset around zone
8  borderRadius?: number // round corner when rectangle
9  keepTooltipPosition?: boolean
10  tooltipBottomOffset?: number
11  children: React.ReactNode
12  withoutButtons?: boolean
13  pressable?: boolean
14  onNext?: (currentStep: IStep | undefined, nextStep: IStep | undefined) => void | 'stop' | 'doNothing'
15  onPrevious?: (currentStep: IStep | undefined, nextStep: IStep | undefined) => void | 'stop' | 'doNothing'
16}
17
18type Shape = 'circle' | 'rectangle' | 'circle_and_keep' | 'rectangle_and_keep'
19
20export interface TourGuideProviderProps {
21  tooltipComponent?: React.ComponentType<TooltipProps>
22  tooltipStyle?: StyleProp<ViewStyle>
23  labels?: Labels
24  startAtMount?: boolean | string //  start at mount, boolean for single tours, string for multiple tours
25  androidStatusBarVisible?: boolean
26  backdropColor?: string
27  verticalOffset?: number
28  wrapperStyle?: StyleProp<ViewStyle>
29  maskOffset?: number
30  borderRadius?: number
31  animationDuration?: number
32  children: React.ReactNode
33  dismissOnPress?: boolean
34  preventOutsideInteraction?:boolean
35}
36
37interface TooltipProps {
38  isFirstStep?: boolean
39  isLastStep?: boolean
40  currentStep: Step
41  labels?: Labels
42  handleNext?(): void
43  handlePrev?(): void
44  handleStop?(): void
45}
46
47interface Labels {
48  skip?: string
49  previous?: string
50  next?: string
51  finish?: string
52}

In order to start the tutorial, you can call the start function from useTourGuideController hook:

1function HomeScreen() {
2  const { start } = useTourGuideController()
3
4  React.useEffect(() => {
5    start()
6  }, [])
7
8
9  render() {
10    // ...
11  }
12}
13
14export default HomeScreen

If you are looking for a working example, please check out this link.

Using Multiple Tours

If you'd like to have multiple tours (different pages, differnt user types, etc) you can pass in a tourKey to useTourGuideController to create a tour that is keyed to that tourKey. Important If you use a keyed tour, in order for the TourGuideZone components to register correctly you must do one of two things. Either (1) pass along the tourKey to the TourGuideZone components, or (2) extract the TourGuideZone components from the hook itself

(1) If you want to pass along the tourKey

1import { TourGuideZone, useTourGuideController } from 'rn-tourguide'
2const {
3  canStart, // <-- These are all keyed to the tourKey
4  start, // <-- These are all keyed to the tourKey
5  stop, // <-- These are all keyed to the tourKey
6  eventEmitter, // <-- These are all keyed to the tourKey
7  tourKey, // <-- Extract the tourKey
8} = useTourGuideController('results')
9
10return (
11  <TourGuideZone
12    tourKey={tourKey} // <-- Pass in the tourKey
13    zone={2}
14    text='Check on your results'
15  >
16    {/** Children */}
17  </TourGuideZone>
18)

Or (2) if you want to extract the components directly from the hook

1import { useTourGuideController } from 'rn-tourguide'
2const { canStart, start, stop, TourGuideZone } =
3  useTourGuideController('results')
4
5return (
6  <TourGuideZone // <-- No need to pass in the tourKey
7    zone={2}
8    text='Check on your results'
9  >
10    {/** Children */}
11  </TourGuideZone>
12)

If you use multiple tours and would like to use the startAtMount prop on the TourGuideProvider component, then pass in the string of the tour you'd like to start

Custom tooltip component

You can customize the tooltip by passing a component to the copilot HOC maker. If you are looking for an example tooltip component, take a look at the default tooltip implementation.

1const TooltipComponent = ({
2  isFirstStep,
3  isLastStep,
4  handleNext,
5  handlePrev,
6  handleStop,
7  currentStep,
8}) => (
9  // ...
10);
11
12<TourGuideProvider {...{tooltipComponent: TooltipComponent}}>
13// ...
14</TourGuideProvider>

Custom tooltip styling

You can customize tooltips style:

1const style = {
2  backgroundColor: '#9FA8DA',
3  borderRadius: 10,
4  paddingTop: 5,
5}
6
7<TourGuideProvider {...{ tooltipStyle: style }}>
8// ...
9</TourGuideProvider>

Custom mask color

You can customize the mask color - default is rgba(0, 0, 0, 0.4), by passing a color string to the copilot HOC maker.

1<TourGuideProvider {...{ backdropColor: 'rgba(50, 50, 100, 0.9)' }}>
2  // ...
3</TourGuideProvider>

Custom labels (for i18n)

You can localize labels:

1<TourGuideProvider
2  {...{
3    labels: {
4      previous: 'Vorheriger',
5      next: 'Nächster',
6      skip: 'Überspringen',
7      finish: 'Beenden',
8    },
9  }}
10>
11  // ...
12</TourGuideProvider>

Listening to the events

Along with start(), useTourGuideController passes copilotEvents function to the component to help you with tracking of tutorial progress. It utilizes mitt under the hood, you can see how full API there.

List of available events is:

• start — Copilot tutorial has started.
• stop — Copilot tutorial has ended or skipped.
• stepChange — Next step is triggered. Passes Step instance as event handler argument.

Prevent Outside Interaction

Sometimes you need to prevent users to interact with app while tour is shown, in such case preventOutsideInteraction prop is up for you.

default: false

1<TourGuideProvider preventOutsideInteraction>
2  <AppContent />
3</TourGuideProvider>

Contributing

Issues and Pull Requests are always welcome.

Hire an expert!

Looking for a ReactNative freelance expert with more than 14 years experience? Contact me from my website!

License

• MIT © 2020 Xavier CARPENTIER SAS, https://xaviercarpentier.com.
• MIT © 2017 OK GROW!, https://www.okgrow.com.