Package Exports

rn-tourguide

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rn-tourguide) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

RN-TourGuide

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

RN Tourguide

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

Use the copilot() higher order component for the screen component that you want to use copilot with:

import { copilot } from 'rn-tourguide'

class HomeScreen extends Component {
  /* ... */
}

export default copilot()(HomeScreen)

Example

import { copilot, TourGuideZone, CopilotWrapper } from 'rn-tourguide'

class HomeScreen {
  render() {
    return (
      <View>
        <TourGuideZone
          zone={1}
          isTourGuide
          text={'Tooltip 1'}
          borderRadius={16}
        >
          <CopilotWrapper>
            <Text style={styles.title}>
              {'Welcome to the demo of\n"rn-tourguide"'}
            </Text>
          </CopilotWrapper>
        </TourGuideZone>
        <TourGuideZone
          zone={2}
          isTourGuide
          text={'Tooltip 2, circle shape'}
          shape={'circle'}
        >
          <CopilotWrapper>
            <Text style={styles.title}>
              {'Welcome to the demo of\n"rn-tourguide"'}
            </Text>
          </CopilotWrapper>
        </TourGuideZone>
      </View>
    )
  }
}

TourGuide props:

interface TourGuideZoneProps {
  zone: number // A positive number indicating the order of the step in the entire walkthrough.
  isTourGuide?: boolean // return children without wrapping id false
  text?: string // text in tooltip
  shape?: Shape // which shape
  maskOffset?: number // offset around zone
  borderRadius?: number // round corner when rectangle
  children: React.ReactNode
}

type Shape = 'circle' | 'rectangle' | 'circle_and_keep' | 'rectangle_and_keep'

interface CopilotOptionProps {
  tooltipComponent?: React.ComponentType<TooltipProps>
  tooltipStyle?: StyleProp<ViewStyle>
  animated?: boolean
  labels?: Labels
  androidStatusBarVisible?: boolean
  backdropColor?: string
  stopOnOutsideClick?: boolean
  verticalOffset?: number
  wrapperStyle?: StyleProp<ViewStyle>
  maskOffset?: number
  animationDuration?: number
}

interface TooltipProps {
  isFirstStep?: boolean
  isLastStep?: boolean
  currentStep: Step
  labels?: Labels
  handleNext?(): void
  handlePrev?(): void
  handleStop?(): void
}

interface Labels {
  skip?: string
  previous?: string
  next?: string
  finish?: string
}

In order to start the tutorial, you can call the start prop function in the root component that is injected by copilot:

class HomeScreen extends Component {
  handleStartButtonPress() {
    this.props.start()
  }

  render() {
    // ...
  }
}

export default copilot()(HomeScreen)

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

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.

const TooltipComponent = ({
  isFirstStep,
  isLastStep,
  handleNext,
  handlePrev,
  handleStop,
  currentStep,
}) => (
  // ...
);

copilot({
  tooltipComponent: TooltipComponent
})(RootComponent)

You can customize tooltips style:

const style = {
  backgroundColor: '#9FA8DA',
  borderRadius: 10,
  paddingTop: 5,
}

copilot({
  tooltipStyle: style,
})(RootComponent)

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.

copilot({
  backdropColor: 'rgba(50, 50, 100, 0.9)',
})(RootComponent)

Custom labels (for i18n)

You can localize labels:

copilot({
  labels: {
    previous: 'Vorheriger',
    next: 'Nächster',
    skip: 'Überspringen',
    finish: 'Beenden',
  },
})(RootComponent)

Triggering the tutorial

Use this.props.start() in the root component in order to trigger the tutorial. You can either invoke it with a touch event or in componentDidMount. Note that the component and all its descendants must be mounted before starting the tutorial since the CopilotSteps need to be registered first.

Listening to the events

Along with this.props.start(), copilot HOC 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.

Example:

import { copilot, CopilotStep } from '@applications-developer/rn-copilot'

const CustomComponent = ({ copilot }) => (
  <View {...copilot}>
    <Text>Hello world!</Text>
  </View>
)

class HomeScreen {
  componentDidMount() {
    this.props.copilotEvents.on('stop', () => {
      // Copilot tutorial finished!
    })
  }

  componentWillUnmount() {
    // Don't forget to disable event handlers to prevent errors
    this.props.copilotEvents.off('stop')
  }

  render() {
    // ...
  }
}

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!

JSPM

rn-tourguide