Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xcarpentier/rn-tourguide
π©Make an interactive step by step tour guide for your react-native app (a rewrite of react-native-copilot)
https://github.com/xcarpentier/rn-tourguide
animation expo flubber mask-svg-path morphing react-native rn-tourguide svg-animations tooltip tourguide tutorial web
Last synced: 11 days ago
JSON representation
π©Make an interactive step by step tour guide for your react-native app (a rewrite of react-native-copilot)
- Host: GitHub
- URL: https://github.com/xcarpentier/rn-tourguide
- Owner: xcarpentier
- License: other
- Created: 2020-05-25T22:50:59.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-07-01T05:07:15.000Z (4 months ago)
- Last Synced: 2024-10-27T19:04:09.861Z (14 days ago)
- Topics: animation, expo, flubber, mask-svg-path, morphing, react-native, rn-tourguide, svg-animations, tooltip, tourguide, tutorial, web
- Language: TypeScript
- Homepage: https://xcarpentier.github.io/rn-tourguide/
- Size: 3.24 MB
- Stars: 736
- Watchers: 12
- Forks: 214
- Open Issues: 60
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
RN-TourGuide
A flexible tourguide for your react native app!
π Webable π
(a rewriting of react-native-copilot)
## Installation
```
yarn add rn-tourguide
``````
yarn add react-native-svg
react-native link react-native-svg
```If you are using Expo:
```
expo install react-native-svg
```## Usage
```tsx
import {
TourGuideProvider, // Main provider
TourGuideZone, // Main wrapper of highlight component
TourGuideZoneByPosition, // Component to use mask on overlay (ie, position absolute)
useTourGuideController, // hook to start, etc.
} from 'rn-tourguide'// Add at the root of you app!
function App() {
return (
// If you added a statusbar in Andoid set androidStatusBarVisible: true as well to avoid vertical position issues
)
}const AppContent = () => {
const iconProps = { size: 40, color: '#888' }// Use Hooks to control!
const {
canStart, // a boolean indicate if you can start tour guide
start, // a function to start the tourguide
stop, // a function to stopping it
eventEmitter, // an object for listening some events
} = useTourGuideController()// Can start at mount π
// you need to wait until everything is registered π
React.useEffect(() => {
if (canStart) {
// π test if you can start otherwise nothing will happen
start()
}
}, [canStart]) // π don't miss it!const handleOnStart = () => console.log('start')
const handleOnStop = () => console.log('stop')
const handleOnStepChange = () => console.log(`stepChange`)React.useEffect(() => {
eventEmitter.on('start', handleOnStart)
eventEmitter.on('stop', handleOnStop)
eventEmitter.on('stepChange', handleOnStepChange)return () => {
eventEmitter.off('start', handleOnStart)
eventEmitter.off('stop', handleOnStop)
eventEmitter.off('stepChange', handleOnStepChange)
}
}, [])return (
{/*Use TourGuideZone only to wrap your component
*/}
{'Welcome to the demo of\n"rn-tourguide"'}
start()}>
START THE TUTORIAL!
start(4)}>
Step 4
start(2)}>
Step 2
Stop
)
}
````TourGuide` props:
```ts
interface TourGuideZoneProps {
zone: number // A positive number indicating the order of the step in the entire walkthrough.
tourKey?: string // A string indicating which tour the zone belongs to
isTourGuide?: boolean // return children without wrapping id false
text?: string // text in tooltip
shape?: Shape // which shape
maskOffset?: number // offset around zone
borderRadius?: number // round corner when rectangle
keepTooltipPosition?: boolean
tooltipBottomOffset?: number
children: React.ReactNode
}type Shape = 'circle' | 'rectangle' | 'circle_and_keep' | 'rectangle_and_keep'
export interface TourGuideProviderProps {
tooltipComponent?: React.ComponentType
tooltipStyle?: StyleProp
labels?: Labels
startAtMount?: boolean | string // start at mount, boolean for single tours, string for multiple tours
androidStatusBarVisible?: boolean
backdropColor?: string
verticalOffset?: number
wrapperStyle?: StyleProp
maskOffset?: number
borderRadius?: number
animationDuration?: number
children: React.ReactNode
dismissOnPress?: boolean
preventOutsideInteraction?:boolean
}interface TooltipProps {
isFirstStep?: boolean
isLastStep?: boolean
currentStep: Step
labels?: Labels
handleNext?(): void
handlePrev?(): void
handleStop?(): void
}interface Labels {
skip?: string
previous?: string
next?: string
finish?: string
}
```In order to start the tutorial, you can call the `start` function from `useTourGuideController` hook:
```js
function HomeScreen() {
const { start } = useTourGuideController()React.useEffect(() => {
start()
}, [])render() {
// ...
}
}export default HomeScreen
```If you are looking for a working example, please check out [this link](https://github.com/xcarpentier/rn-tourguide/blob/master/App.tsx).
## Using Multiple Tours
If you'd like to have multiple tours (different pages, differnt user types, etc) you can pass in a `tourKey` to `useTourGuideController` to create a tour that is keyed to that `tourKey`. **Important** If you use a keyed tour, in order for the `TourGuideZone` components to register correctly you _must_ do one of two things. Either (1) pass along the `tourKey` to the `TourGuideZone` components, or (2) extract the `TourGuideZone` components from the hook itself
(1) If you want to pass along the tourKey
```ts
import { TourGuideZone, useTourGuideController } from 'rn-tourguide'
const {
canStart, // <-- These are all keyed to the tourKey
start, // <-- These are all keyed to the tourKey
stop, // <-- These are all keyed to the tourKey
eventEmitter, // <-- These are all keyed to the tourKey
tourKey, // <-- Extract the tourKey
} = useTourGuideController('results')return (
{/** Children */}
)
```Or (2) if you want to extract the components directly from the hook
```ts
import { useTourGuideController } from 'rn-tourguide'
const { canStart, start, stop, TourGuideZone } =
useTourGuideController('results')return (
{/** Children */}
)
```If you use multiple tours and would like to use the `startAtMount` prop on the `TourGuideProvider` component, then pass in the string of the tour you'd like to start
### Custom tooltip component
You can customize the tooltip by passing a component to the `copilot` HOC maker. If you are looking for an example tooltip component, take a look at [the default tooltip implementation](https://github.com/xcarpentier/rn-tourguide/blob/master/src/components/Tooltip.tsx).
```js
const TooltipComponent = ({
isFirstStep,
isLastStep,
handleNext,
handlePrev,
handleStop,
currentStep,
}) => (
// ...
);// ...
```
### Custom tooltip styling
You can customize tooltips style:
```tsx
const style = {
backgroundColor: '#9FA8DA',
borderRadius: 10,
paddingTop: 5,
}// ...
```
### Custom mask color
You can customize the mask color - default is `rgba(0, 0, 0, 0.4)`, by passing a color string to the `copilot` HOC maker.
```tsx
// ...
```
### Custom labels (for i18n)
You can localize labels:
```tsx
// ...
```
### Listening to the events
Along with `start()`, `useTourGuideController` passes `copilotEvents` function to the component to help you with tracking of tutorial progress. It utilizes [mitt](https://github.com/developit/mitt) under the hood, you can see how full API there.
List of available events is:
- `start` β Copilot tutorial has started.
- `stop` β Copilot tutorial has ended or skipped.
- `stepChange` β Next step is triggered. Passes [`Step`](https://github.com/mohebifar/react-native-copilot/blob/master/src/types.js#L2) instance as event handler argument.### Prevent Outside Interaction
Sometimes you need to prevent users to interact with app while tour is shown, in such case `preventOutsideInteraction` prop is up for you.
```default: false```
```jsx
```
## Contributing
Issues and Pull Requests are always welcome.
## Hire an expert!
Looking for a ReactNative freelance expert with more than 14 years experience? Contact me from myΒ [website](https://xaviercarpentier.com)!
## License
- [MIT](LICENSE) Β© 2020 Xavier CARPENTIER SAS, https://xaviercarpentier.com.
- [MIT](LICENSE) Β© 2017 OK GROW!, https://www.okgrow.com.