https://github.com/stackbuilders/react-native-spotlight-tour
A highly customizable tour feature with an awesome spotlight effect
https://github.com/stackbuilders/react-native-spotlight-tour
android app-tour customizable hacktoberfest ios react react-native spotlight spotlight-tour step-by-step tour user-guide
Last synced: 9 months ago
JSON representation
A highly customizable tour feature with an awesome spotlight effect
- Host: GitHub
- URL: https://github.com/stackbuilders/react-native-spotlight-tour
- Owner: stackbuilders
- License: mit
- Created: 2020-08-06T16:06:02.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-06T16:25:42.000Z (9 months ago)
- Last Synced: 2025-05-06T17:37:58.999Z (9 months ago)
- Topics: android, app-tour, customizable, hacktoberfest, ios, react, react-native, spotlight, spotlight-tour, step-by-step, tour, user-guide
- Language: TypeScript
- Homepage: https://stackbuilders.github.io/react-native-spotlight-tour/
- Size: 29.8 MB
- Stars: 361
- Watchers: 22
- Forks: 31
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# React Native Spotlight Tour
[](#contributors-)
[](https://github.com/stackbuilders/react-native-spotlight-tour/actions/workflows/ci.yml)
[](https://github.com/stackbuilders/react-native-spotlight-tour/actions/workflows/release.yml)
[](https://www.npmjs.com/package/react-native-spotlight-tour)
[](https://www.npmjs.com/package/react-native-spotlight-tour)
[](https://github.com/stackbuilders/react-native-spotlight-tour/blob/main/LICENSE)
[](https://github.com/stackbuilders/react-native-spotlight-tour/releases)
[](https://snyk.io/test/github/stackbuilders/react-native-spotlight-tour)
`react-native-spotlight-tour` is a simple and intuitive library for React Native (Android, iOS, and Web
compatible). It uses [Floating UI](https://floating-ui.com) 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
## Requirements
- [ReactJS](https://reactjs.org/) >= 16.8.0
- [React Native](https://reactnative.dev/) >= 0.50.0
- [react-native-svg](https://github.com/react-native-svg/react-native-svg) >= 12.1.0
## Install
With `npm`:
```bash
npm install react-native-spotlight-tour
```
With `yarn`:
```bash
yarn add react-native-spotlight-tour
```
## 🚨 Breaking changes: v2 to v3
This 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-tour` to just `react-native-spotlight-tour`
- Don't worry, this library is still developed and maintained by the [Stack Builders Inc.](https://www.stackbuilders.com/) team!
- Remove the former package from your dependencies and use the command described in the [Install section](#install)
- Rename any import from the previous name to use just `react-native-spotlight-tour` instead
- Tooltip positioning was refactored
- Props related to the tooltip position were removed from `SpotlightTourProvider` and the `TourStep` object.
- Both `Align` and `Position` enums were removed
- Both `alignTo` and `position` props were removed
- We now delegate the positioning to [FloatingUI](https://floating-ui.com/), so you can use the `floatingProps` prop to configure its global behavior or granularly on each step.
- Middleware functions are re-exported from `@floating-ui/react-native` to `react-native-spotlight-tour`.
- You may not need to do changes on `floatingProps` since the default behavior is very similar to v2
## Usage
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.
```tsx
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 (
{({ start }) => (
<>
Introduction
This is an example using the spotlight-tour library.
Press the Start button to see it in action.
Documentation
Please, read the documentation before installing.
>
)};
);
```
Floating-UI props can be defined in the `` 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 `` index. Bellow is a complete example of a `TourStep` array:
```tsx
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 }) => (
This is the first step of tour!
)
}, {
before: () => {
return DataService.fetchData()
.then(setData);
},
render: () => {
// You can also use the hook inside the step component!
const { previous, stop } = useSpotlightTour();
return (
This is the first step of tour!
);
}
}];
```
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 ``.
You can also find a complete example [here](example/).
## Built-in Helper Components
You can take advantage of the built-in customizable components. For example, our [TourBox](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/#tourbox) component can be used as a tooltip container for each step.
```tsx
import { Text } from "react-native";
import { Align, TourBox, TourStep } from "react-native-spotlight-tour";
const tourSteps: TourStep[] = [{
render: props => (
{"This is the third step of tour example.\n"}
{"If you want to go to the next step, please press "}{"Next.\n"}
{"If you want to go to the previous step, press "}{"Previous.\n"}
),
}];
```
### Tour customization
The [SpotlightTourProvider](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/#spotlighttourprovider) also allows you to customize the overlay through the [overlayColor](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/SpotlightTourProviderProps.html#overlaycolor) and [overlayOpacity](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/interfaces/SpotlightTourProviderProps.html#overlayopacity) props.
```tsx
import { AttachStep, SpotlightTourProvider, TourStep } from "react-native-spotlight-tour";
const mySteps: TourStep[] = [
// ...
];
return (
{({ start }) => (
<>
{/* ... */}
>
)};
);
```
Besides above customizations, you can also define the transition animation [see motion](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/#motion) and the behavior when the user presses the backdrop [see onBackdropPress](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/#backdroppressbehavior). Otherwise if you wish to make them different for an specific step you could override this properties in the `TourStep` configuration.
```tsx
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 => (
{"This is the first step of tour example.\n"}
{"If you want to go to the next step, please press "}{"Next.\n"}
{"If you want to go to the previous step, press "}{"Previous.\n"}
),
}];
return (
{({ start }) => (
<>
Introduction
This is an example using the spotlight-tour library.
Press the Start button to see it in action.
>
)};
);
```
## API Reference
To view all the types, options, and props, please check the complete [API Reference](https://stackbuilders.github.io/react-native-spotlight-tour/docs/build/) documentation.
## Contributing
Do you want to contribute to this project? Please take a look at our [contributing guideline](/docs/CONTRIBUTING.md) to know how you can help us build it.
---
[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Jose Luis Leon
💻 ⚠️ 📖 🚇 🚧 👀
Sebastián Estrella
🚇
Angie Rojas
💻 📖
Fernanda Andrade
🚇 ⚠️
Steven Cuasqui
📖
Alexander Mejía
💻
Carolina López
💻 💡
cmarcag
⚠️
Ricardo Arrobo
💻 📖
Mohammad Abkal
📖
Alexander Pokhil
💻
Alejandro Vivanco
💻 👀
Wellington Mendoza
👀
Christian Samaniego
👀
beKool.sh
📖
Alexander Pokhil
💻
Ravan Scafi
💻
Andres Perez
💻
David Baldassari
💻
Add your contributions
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
## License
MIT, see [the LICENSE file](LICENSE).