react-native-spotlight-tour is a simple and intuitive library for React Native (Android, iOS, and Web
compatible). It uses Floating UI under the hood in order to handle elements
positioning, it re-exports all floating-ui middlewares to be configured in the tour.
It also 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
- ReactJS >= 16.8.0
- React Native >= 0.50.0
- react-native-svg >= 12.1.0
With npm:
npm install react-native-spotlight-tourWith yarn:
yarn add react-native-spotlight-tourThis major update brings a few fixes, some great new features, and some breaking changes. These are some highlight you’ll need to consider while upgrading from v2 to v3:
- The package has been renamed from
@stackbuilders/react-native-spotlight-tourto justreact-native-spotlight-tour- Don’t worry, this library is still developed and maintained by the Stack Builders Inc. team!
- Remove the former package from your dependencies and use the command described in the Install section
- Rename any import from the previous name to use just
react-native-spotlight-tourinstead
- Tooltip positioning was refactored
- Props related to the tooltip position were removed from
SpotlightTourProviderand theTourStepobject.- Both
AlignandPositionenums were removed - Both
alignToandpositionprops were removed
- Both
- We now delegate the positioning to FloatingUI, so you can use the
floatingPropsprop to configure its global behavior or granularly on each step. - Middleware functions are re-exported from
@floating-ui/react-nativetoreact-native-spotlight-tour. - You may not need to do changes on
floatingPropssince the default behavior is very similar to v2
- Props related to the tooltip position were removed from
To be able to use the tour, you’ll need to wrap everything around a SpotlightTourProvider. This provider component will also give you access to a hook to retrieve the SpotlightTour context, which gives information and fine control over the tour.
import { Button, Text, View } from "react-native";
import {
AttachStep,
SpotlightTourProvider,
TourStep,
flip,
offset,
shift,
} from "react-native-spotlight-tour";
const mySteps: TourStep[] = [
// ...setup the steps
];
return (
<SpotlightTourProvider
steps={mySteps}
overlayColor={"gray"}
overlayOpacity={0.36}
// This configurations will apply to all steps
floatingProps={{
middleware:[offset(5), shift(), flip()],
placement: "bottom",
}}
>
{({ 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}>
<Text>Documentation</Text>
</AttachStep>
<DescriptionText>
Please, read the documentation before installing.
</DescriptionText>
</View>
</>
)};
</SpotlightTourProvider>
);Floating-UI props can be defined in the <SpotlightTourProvider/> and this will be applied to all tour steps. If no configuration is given it will take a default with the next values:
middlewares: [flip(), offset(4), shift()] and placement: "bottom".
The tour requires an array of steps to be configured, which will map directly to each <AttachStep /> index. Bellow is a complete example of a TourStep array:
import { Button, Text, View } from "react-native";
import {
Align,
TourStep,
useSpotlightTour
} from "react-native-spotlight-tour";
const mySteps: TourStep[] = [{
// This configurations will apply just for this step
floatingProps:{
middleware: [offset(0), shift(), flip()],
placement: "right",
},
render: ({ next }) => (
<View>
<Text>This is the first step of tour!</Text>
<Button title="Next" onPress={next} />
</View>
)
}, {
before: () => {
return DataService.fetchData()
.then(setData);
},
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>
);
}
}];Floating-UI props can be defined in each step for a custom configuration. If no floating configuration is specified in the step it will take the one defined in the <SpotlightTourProvider/>.
You can also find a complete example here.
You can take advantage of the built-in customizable components. For example, our TourBox component can be used as a tooltip container for each step.
import { Text } from "react-native";
import { Align, TourBox, TourStep } from "react-native-spotlight-tour";
const tourSteps: TourStep[] = [{
render: props => (
<TourBox
title="Tour: Customization"
titleStyle={{
fontFamily: 'Roboto',
color: '#90EE90',
fontWeight: 'bold'
}}
backText="Previous"
nextText="Next"
{...props}
>
<Text>
{"This is the third step of tour example.\n"}
{"If you want to go to the next step, please press "}<BoldText>{"Next.\n"}</BoldText>
{"If you want to go to the previous step, press "}<BoldText>{"Previous.\n"}</BoldText>
</Text>
</TourBox>
),
}];The SpotlightTourProvider also allows you to customize the overlay through the overlayColor and overlayOpacity props.
import { AttachStep, SpotlightTourProvider, TourStep } from "react-native-spotlight-tour";
const mySteps: TourStep[] = [
// ...
];
return (
<SpotlightTourProvider steps={mySteps} overlayColor={"gray"} overlayOpacity={0.36}>
{({ start }) => (
<>
{/* ... */}
</>
)};
</SpotlightTourProvider>
);Besides above customizations, you can also define the transition animation see motion and the behavior when the user presses the backdrop see onBackdropPress. Otherwise if you wish to make them different for an specific step you could override this properties in the TourStep configuration.
import { Button, Text, View } from "react-native";
import {
Align
AttachStep,
SpotlightTourProvider,
TourStep,
TourBox
} from "react-native-spotlight-tour";
const tourSteps: TourStep[] = [{
motion: "fade",
onBackdropPress: "stop",
render: props => (
<TourBox
title="Tour: Customization"
backText="Previous"
nextText="Next"
{...props}
>
<Text>
{"This is the first step of tour example.\n"}
{"If you want to go to the next step, please press "}<BoldText>{"Next.\n"}</BoldText>
{"If you want to go to the previous step, press "}<BoldText>{"Previous.\n"}</BoldText>
</Text>
</TourBox>
),
}];
return (
<SpotlightTourProvider
steps={tourSteps}
overlayColor={"gray"}
overlayOpacity={0.36}
onBackdropPress="continue"
motion="bounce"
>
{({ 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>
</>
)};
</SpotlightTourProvider>
);To view all the types, options, and props, please check the complete API Reference documentation.
Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT, see the LICENSE file.
