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
.
Prop | Required? | Default | Description |
---|---|---|---|
ref |
No | N/A | Mutable object for the Tour. Populated through the provider. |
steps |
Yes | N/A | Steps for the tour (array of TourStep ). |
overlayColor |
No | black |
Color for the overlay (String , Number or rgbaArray ). |
overlayOpacity |
No | 0.45 |
Opacity of the overlay (Number or String ) |
Method | Description |
---|---|
start |
Begin the tour. |
next |
Navigate to the next defined step. |
previous |
Navigate to the previous step. |
stop |
Finish the tour. |
AttachStep
The AttachStep
wraps the components that will be highlighted by the library. It receives the
following properties:
Prop | Required? | Default | Description |
---|---|---|---|
index |
Yes | N/A | Defines the order for the tour sequence (Number ). |
disabled |
No | false |
Defines if the library should highlight the component or not (Boolean ). |
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:
Prop | Required? | Default | Description |
---|---|---|---|
alignTo |
No | Align.SPOT |
Aligns the step component to the Align.SPOT or the Align.SCREEN . |
before |
No | Promise.resolve() |
If present, it runs an operation before a step starts. The function can return either void , or Promise<void> . |
render |
Yes | - | A function component that will be rendered in the step. The props of this component should include the RenderProps. |
position |
Yes | - | The position with respect to the spot where the step component will be rendered. Possible values are Position.BOTTOM , Position.LEFT , Position.RIGHT , or Position.TOP |
Render props
These props will be passed to the function component of render
in a TourStep
object. The props contain the following:
Prop | Type | Description |
---|---|---|
current |
number |
The current step index. Starting from 0 . |
isFirst |
boolean |
True if the current step is the first step. False otherwise. |
isLast |
boolean |
True if the current step is the last step. False otherwise. |
next |
() => void |
Calling it will trigger the next step (if any). |
previous |
() => void |
Calling it will trigger the previous step (if any). |
stop |
() => void |
Calling it will end the tour. |
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