@shankulkarni/react-native-spotlight-tour v0.1.17

React Native Spotlight Tour

react-native-spotlight-tour is a simple and intuitive library for React Native (Android and iOS compatible). It allows you to implement a highly customizable tour feature with an awesome spotlight effect. This library handles animations at the native level and is perfect for the following:

• Guiding users on how to use your application
• Showing an introduction to your users

Requirements

• react >= 16.8.0
• react-native >= 0.50.0
• react-native-svg >= 12.1.0

Installation

With npm:

$ npm install @stackbuilders/react-native-spotlight-tour

With yarn:

$ yarn add @stackbuilders/react-native-spotlight-tour

Basic usage

import { AttachStep, SpotlightTourProvider, TourStep } from "@stackbuilders/react-native-spotlight-tour";

const mySteps: TourStep[] = [
  ...
];

...
  <SpotlightTourProvider steps={mySteps} overlayColor={"gray"} overlayOpacity={0.36}>
    {({ start }) => (
      <>
        <Button title="Start" onPress={start} />

        <View>
          <AttachStep index={0}>
            <Text>Introduction</Text>
          </AttachStep>

          <Text>
            This is an example using the spotlight-tour library.
            Press the Start button to see it in action.
          </Text>
        </View>

        <View>
          <AttachStep index={1}>
            <TitleText>Documentation</TitleText>
          </AttachStep>
          <DescriptionText>
            Please, read the documentation before installing.
          </DescriptionText>
        </View>
      </>
    )};
  </SpotlightTourProvider>
  ...

SpotlightTourProvider

The SpotlightTourProvider allows you to wrap a section of the application to implement the spotlight tour. In this section, you can define a component that will trigger the tour sequence. For example, a button with an onPress handler that will allow you to call the provided start() method to start the tour workflow. To customize and set up this workflow, you should pass a list of steps to the SpotlightTourProvider. Check out the tour steps section for more details.

Once the tour starts, an overlay component will be shown to highlight a component from the section. This library shows an overlay component that darkens other UI elements on the screen so that users can focus on the children's components of AttachStep.

AttachStep

The AttachStep wraps the components that will be highlighted by the library. It receives the following properties:

Setting Tour Steps

The TourStep lets you render a component with the information you want to display for each step in the tour. It has the following properties:

Render props

These props will be passed to the function component of render in a TourStep object. The props contain the following:

Bellow is a complete example of a TourStep array:

import {
  Align,
  Position,
  TourStep,
  useSpotlightTour
} from "@stackbuilders/react-native-spotlight-tour";

const mySteps: TourStep[] = [{
  alignTo: Align.SCREEN,
  position: Position.BOTTOM,
  render: ({ next }) => (
    <View>
      <Text>This is the first step of tour!</Text>
      <Button title="Next" onPress={next} />
    </View>
  )
}, {
  alignTo: Align.SPOT,
  before: () => {
    return DataService.fetchData()
      .then(setData);
  },
  position: Position.RIGHT,
  render: () => {
    // You can also use the hook inside the step component!
    const { previous, stop } = useSpotlightTour();

    return (
      <View>
        <Text>This is the first step of tour!</Text>
        <Button title="Previous" onPress={previous} />
        <Button title="Stop" onPress={stop} />
      </View>
    );
  }
}];

Check out the complete example here.

Contributing

Contributions are always welcome! If you are interested in contributing, please check out our Conduct Code.

To run the library code locally, please consider the following versions:

• nodejs >= 14.7.0
• yarn >= 1.22.4

License

MIT License.