Skip to content

Latest commit

 

History

History
350 lines (291 loc) · 18.5 KB

README.md

File metadata and controls

350 lines (291 loc) · 18.5 KB
Raw

React Native Spotlight Tour

All Contributors

CI Release NPM version NPM downloads NPM license GitHub Release Date Known Vulnerabilities

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

spotlight-bounce-gif spotlight-fade-gif spotlight-slide-gif spotlight-rect-gif

Requirements

Install

With npm:

npm install react-native-spotlight-tour

With yarn:

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. 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-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, 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.

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.

Built-in Helper Components

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>
    ),
  }];

Tour customization

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>
);

API Reference

To view all the types, options, and props, please check the complete API Reference documentation.

Contributing

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.

Stack Builders Check out our libraries | Join our team

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jose Luis Leon
Jose Luis Leon
💻 ⚠️ 📖 🚇 🚧 👀		 Sebastián Estrella
Sebastián Estrella
🚇		 Angie Rojas
Angie Rojas
💻 📖		 Fernanda Andrade
Fernanda Andrade
🚇 ⚠️		 Steven Cuasqui
Steven Cuasqui
📖		 Alexander Mejía
Alexander Mejía
💻		 Carolina López
Carolina López
💻 💡
cmarcag
cmarcag
⚠️		 Ricardo Arrobo
Ricardo Arrobo
💻 📖		 Mohammad Abkal
Mohammad Abkal
📖		 Alexander Pokhil
Alexander Pokhil
💻		 Alejandro Vivanco
Alejandro Vivanco
💻 👀		 Wellington Mendoza
Wellington Mendoza
👀		 Christian Samaniego
Christian Samaniego
👀
beKool.sh
beKool.sh
📖
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT, see the LICENSE file.