## Documentation
[https://docs.react.tours](https://docs.react.tours/tour/quickstart)
> This documentation is for the latest release, which uses [npm scoped package](https://docs.npmjs.com/cli/v7/using-npm/scope) `@reactour`. The original `reactour` is now on branch `v1` and its documentation can be found [here](https://github.com/elrumordelaluz/reactour/tree/v1).
## Install
```zsh
npm i -S @reactour/tour
# or
yarn add @reactour/tour
```
## Usage
Add the `TourProvider` at the root of your Application, passing the `steps` of the elements to highlight during the _Tour_.
```js
// ...
import { TourProvider } from '@reactour/tour'
ReactDOM.render(
,
document.getElementById('root')
)
const steps = [
{
selector: '.first-step',
content: 'This is my first Step',
},
// ...
]
```
Then somewhere down the Application tree, control the Tour using `useTour` hook.
```js
import { useTour } from '@reactour/tour'
function App() {
const { setIsOpen } = useTour()
return (
<>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at
finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta
metus nec, porta luctus orci
)
}
```
## Examples
#### Playground
The [Playground](https://github.com/elrumordelaluz/reactour/tree/main/packages/playground) is the perfect place to play aroud with all `@reactour` _Components_. [Here](https://reactour.vercel.app) is an online version.
#### Sandboxes
- [Using React Router](https://codesandbox.io/s/reactour-tour-demo-using-react-router-dom-kujql)
- [Using React Router with automatic route switching](https://codesandbox.io/s/tour-demo-using-react-router-dom-with-automatic-route-switching-fhdnxb?file=/src/App.js)
- [Using React Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-modal-8v0eo)
- [Using Semantic UI Modal](https://codesandbox.io/s/reactour-tour-demo-using-semantic-ui-modal-xmqee)
- [Using React Bootstrap Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-bootstrap-modal-qjws4)
- [Tour with data fetching](https://codesandbox.io/s/tour-with-data-fetching-dv2q0?file=/src/index.js)
[](https://codesandbox.io/s/reactour-tour-demo-template-fglzv?fontsize=14&hidenavigation=1&theme=dark)
> Feel free to make a PR proposing new sandboxes or demos to add in the playground.
## `TourProvider`
### `steps?: StepType[]`
Array of elements to highlight with special info and props.
StepType
#### `selector: string | Element`
A string containing one [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to match and highlight the element at the time of this step.
#### `content: string | ({ setCurrentStep, transition, isHighlightingObserved, currentStep, setIsOpen }) => void`
The content to show inside the _Popover_ at the time of this step. Using a `function` have parameters to use inside content.
#### `position?: 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]`
The preferred postion to position the _Popover_ in relation with the highlighted element. Will be automatically calculated in case of unavailable space.
#### `highlightedSelectors?: string[]`
Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to be included (by union) in the highlighted region of the _Mask_.
#### `mutationObservables?: string[]`
Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that addition or removal will triggered a rerender of the _Mask_ shape.
#### `resizeObservables?: string[]`
Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that when resizeing each will triggered a rerender of the _Mask_ shape.
#### `navDotAriaLabel?: string`
String to assign to `aria-label` attribute of the _Dot_ of this step.
#### `stepInteraction?: boolean`
Allow to reenable the interaction for this specific step, when `disableInteraction` (from _TourProvider_) is `true`.
#### `action?: (elem: Element | null) => void`
Action fired when the _Tour_ arrives in this step.
#### `actionAfter?: (elem: Element | null) => void`
Action fired when the _Tour_ leaves this step.
#### `disableActions?: boolean`
Allow to disable all possible actions (interaction with _Mask_, _Navigation Arrows_, _Navigation Dots_, _Close_ button and keyboard events) when the _Tour_ is in this step.
#### `padding?: Padding`
Control padding spaces for this specific step.
#### `bypassElem?: boolean`
Excludes the main `selector` when calculating highlited area if present `highlightedSelectors`.
#### `styles?: StylesObj & PopoverStylesObj & MaskStylesObj`
Customize styles fro this specific step.
### `components?: PopoverComponentsType`
Prop to customize granurally each Component inside the _Popover_.
#### Components available
| key | props |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Badge` | `styles` |
| `Close` | `styles`, `onClick`, `disabled` |
| `Content` | `content`,`setCurrentStep`,`transition`, `isHighlightingObserved`,`currentStep`,`setIsOpen` |
| `Navigation` | `styles`,`setCurrentStep`, `steps`, `currentStep`, `disableDots`, `nextButton`, `prevButton`, `setIsOpen`, `hideButtons`, `hideDots`, `disableAll`, `rtl`, `Arrow`, |
| `Arrow` | `styles`, `inverted`, `disabled` |
Example
```js
import { components } from '@reactour/tour'
function Badge({ children }) {
return (
({ ...base, backgroundColor: 'red' }) }}
>
👉 {children} 👈
)
}
function Close({ onClick }) {
return (
)
}
const steps = [
/* ... */
]
export default function App() {
return (
{/* ... */}
)
}
```
### `styles?: StylesObj & PopoverStylesObj & MaskStylesObj`
Prop to customize styles for the different parts of the _Mask_, _Popover_ and _Tour_ using a function that allows to extend the base styles an take advantage of some state props.
#### Style keys and props available
Refer to [Mask docs](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask) and [Popover docs](https://github.com/elrumordelaluz/reactour/tree/main/packages/popover) for its specific Components
##### Tour Components
| key | props |
| ---------- | ----------------------------------- |
| `badge` | |
| `controls` | |
| `button` | `disabled` |
| `arrow` | `disabled` |
| `dot` | `current`, `disabled`, `showNumber` |
| `close` | `disabled` |
Example
```js
const styles = {
maskWrapper: (base) => ({
...base,
color: 'red',
}),
highlightedArea: (base, { x, y }) => ({
...base,
x: x + 10,
y: y + 10,
}),
badge: (base) => ({ ...base, color: 'blue' }),
}
```
### `padding?: Padding`
Type details
```ts
type Padding =
| number
| {
mask?: ComponentPadding
popover?: ComponentPadding
wrapper?: ComponentPadding
}
// x and y same value or [x, y] or [top, x, bottom] or [top, right, bottom, left]
type ComponentPadding = number | number[]
```
Extra space to add between the _Mask_ and the _Popover_ and the highlighted element. A single number coordinates both spaces. Otherwise, passing an `Object` specifying the Component space.
### `position?: Position`
Type details
```ts
type Position =
| 'top'
| 'right'
| 'bottom'
| 'left'
| 'center'
| [number, number]
| ((postionsProps: PositionProps) => Position)
type PositionProps = {
bottom: number
height: number
left: number
right: number
top: number
width: number
windowWidth: number
windowHeight: number
}
```
Set a global position for the _Popover_ in all steps, fixed in case of `[number, number]`, calculated in case of position `string`
### `setCurrentStep: Dispatch>`
Function to control the _Tour_ current step state.
### `currentStep: number`
Custom _Tour_ current `step` state.
This option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop.
### `disableInteraction?: boolean | ((clickProps: Pick) => boolean)`
Disables the ability to click or interact in any way with the Highlighted element on every step.
This option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop.
### `disableFocusLock?: boolean`
The _Tour_ uses [FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) in order to lock the `focus` iteration inside the _Popover_ when _Tour_ is active. This prop allows to disable this behaviour.
### `disableDotsNavigation?: boolean`
Disable interactivity with _Dot_ navigation inside _Popover_.
### `disableWhenSelectorFalsy?: boolean`
If true, don't show tours when `selector` or `document.getElementById(step.selector)` is falsy.
### `disableKeyboardNavigation?: boolean | KeyboardParts[]`
Type details
```ts
type KeyboardParts = 'esc' | 'left' | 'right'
```
Disable all keyboard navigation events when `true`, disable only selected keys when array.
default: `false`
### `className?: string`
[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Popover_.
default: `reactour__popover`
### `maskClassName?: string`
[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Mask_.
default: `reactour__mask`
### `highlightedMaskClassName?: string`
[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to highlighted part of _Mask_. Useful when using [`disableInteraction`](#disableinteraction-boolean).
### `nextButton?: (props: BtnFnProps) => void`
### `prevButton?: (props: BtnFnProps) => void`
Type details
```ts
type BtnFnProps = {
Button: React.FC
setCurrentStep: Dispatch>
stepsLength: number
currentStep: number
setIsOpen: Dispatch>
}
type NavButtonProps = {
onClick?: () => void
kind?: 'next' | 'prev'
hideArrow?: boolean
}
```
Helper functions to customize the _Next_ and _Prev_ buttons inside _Popover_, with useful parameters. It is possible to use the base `Button` and customize the props.
### `afterOpen?: (target: Element | null) => void`
Action fired just after the _Tour_ is open.
### `beforeClose?: (target: Element | null) => void`
Action fired just before the _Tour_ is closed.
### `onClickMask?: (clickProps: ClickProps) => void`
Type details
```ts
type ClickProps = {
setIsOpen: Dispatch>
setCurrentStep: Dispatch>
setSteps: Dispatch>
setMeta: Dispatch>
currentStep: number
steps: StepType[]
meta: string
}
```
Function that overrides the default close behavior of the _Mask_ click handler. Comes with useful parameters to play with.
### `onClickClose?: (clickProps: ClickProps) => void`
Type details
```ts
type ClickProps = {
setIsOpen: Dispatch>
setCurrentStep: Dispatch>
setSteps: Dispatch>
setMeta: Dispatch>
currentStep: number
steps: StepType[]
meta: string
}
```
Function that overrides the default close behavior of the _Close icon_ click handler. Comes with useful parameters to play with.
### `onClickHighlighted?: (e: MouseEventHandler, clickProps: ClickProps) => void`
Click handler for highlighted area. Only works when `disableInteraction` is active. Useful in case is needed to avoid `onClickMask` when clicking the highlighted element.
Example
```jsx
{
console.log('No interaction at all')
if (clickProps.currentStep < 2) {
e.stopPropagation()
event.preventDefault()
clickProps.setCurrentStep(
Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
)
}
}}
>
{/* ... */}
```
Type details
```ts
type ClickProps = {
setIsOpen: Dispatch>
setCurrentStep: Dispatch>
setSteps: Dispatch>
setMeta: Dispatch>
currentStep: number
steps: StepType[]
meta: string
}
```
### `keyboardHandler?: KeyboardHandler`
Function to handle keyboard events in a custom way.
Type details
```ts
type KeyboardHandler = {
keyboardHandler?: (
e: KeyboardEvent,
clickProps?: ClickProps,
status?: {
isEscDisabled?: boolean
isRightDisabled?: boolean
isLeftDisabled?: boolean
}
) => void
}
```
Example
```jsx
{
if (e.key === 'ArrowRight') {
clickProps.setCurrentStep(
Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
)
}
if (e.key === 'ArrowLeft') {
clickProps.setCurrentStep(Math.max(clickProps.currentStep - 1, 0))
}
if (e.key === 'Escape') {
const nextStep = Math.floor(Math.random() * clickProps.steps.length)
clickProps.setCurrentStep(nextStep)
}
}}
>
{/* ... */}
```
### `badgeContent?: (badgeProps: BadgeProps) => any`
Type details
```ts
type BadgeProps = {
totalSteps: number
currentStep: number
transition: boolean
}
```
Function to customize the content of the _Badge_ using helper parameters like the current and total steps and if the _Tour_ is transitioning between steps.
### `showNavigation?: boolean`
Show or hide the _Navigation_ (_Prev_ and _Next_ buttons and _Dots_) inside _Popover_.
### `showPrevNextButtons?: boolean`
Show or hide _Prev_ and _Next_ buttons inside _Popover_.
### `showCloseButton?: boolean`
Show or hide the _Close_ button inside _Popover_.
### `showBadge?: boolean`
Show or hide the _Badge_ inside _Popover_.
### `showDots?: boolean`
Show or hide _dots_ navigation inside _Popover_.
### `scrollSmooth?: boolean`
Activate `smooth` scroll behavior when steps are outside viewport.
default: `false`
### `inViewThreshold?: { x?: number, y?: number } | number`
Tolerance in pixels to add when calculating if the step element is outside viewport to scroll into view.
### `accessibilityOptions?: A11yOptions`
Type details
```ts
type A11yOptions = {
ariaLabelledBy: string
closeButtonAriaLabel: string
showNavigationScreenReaders: boolean
}
```
Configure generic accessibility related attributes like [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute), [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) for _Close_ button and if show or hide _Dot_ navigation in screen readers.
### `rtl?: boolean`
Option to navigate and show _Navigation_ in right-to-left mode
### `maskId?: string`
Mask ID to pass directly into the [Mask component](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask#maskid-string)
### `clipId?: string`
Clip ID to pass directly into the [Mask component](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask#clipid-string)
### `onTransition?: PositionType`
Function to control the behavior of _Popover_ when is transitioning/scrolling from one step to another, calculating with _Popover_ next position and previous one
Type details
```ts
type PositionType = (
postionsProps: PositionProps,
prev: RectResult
) => 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]
```
### `ContentComponent?: ComponentType`
Completelly custom component to render inside the _Popover_.
Type details
```ts
type PopoverContentProps = {
styles?: StylesObj & PopoverStylesObj & MaskStylesObj
badgeContent?: (badgeProps: BadgeProps) => any
components?: PopoverComponentsType
accessibilityOptions?: A11yOptions
disabledActions?: boolean
onClickClose?: (clickProps: ClickProps) => void
setCurrentStep: Dispatch>
currentStep: number
transition?: boolean
isHighlightingObserved?: boolean
setIsOpen: Dispatch>
steps: StepType[]
showNavigation?: boolean
showPrevNextButtons?: boolean
showCloseButton?: boolean
showBadge?: boolean
nextButton?: (props: BtnFnProps) => void
prevButton?: (props: BtnFnProps) => void
disableDotsNavigation?: boolean
rtl?: boolean
}
```
Example
```js
function ContentComponent(props) {
const isLastStep = props.currentStep === props.steps.length - 1
const content = props.steps[props.currentStep].content
return (
{/* Check if the step.content is a function or a string */}
{typeof content === 'function'
? content({ ...props, someOtherStuff: 'Custom Text' })
: content}
)
}
const steps = [
/* ... */
]
function App() {
return (
({ ...base, padding: 0 }) }}
>
{/* ... */}
)
}
```
### `Wrapper?: ComponentType`
Element which wraps the Tour, useful in case is needed to port the Tour into a [Portal](https://reactjs.org/docs/portals.html). Defaults to `React.Fragment`
## `useTour`
Later in any Component down in the tree of _TourProvider_ you can control the _Tour_ in many ways
```jsx
import { useTour } from '@reactour/tour'
function MyComponent() {
const { isOpen, currentStep, steps, setIsOpen, setCurrentStep, setSteps } = useTour()
return (
<>
{isOpen ? 'Welcome to the tour!' : 'Thank you for participate!'}
Now you are visiting the place {currentStep + 1} of {steps.length}
)
}
```
### `isOpen: boolean`
Is the _Tour_ open or close
### `currentStep: number`
The current step. **zero based**
### `steps: StepType[]`
The `Array` of steps set currently
### `setIsOpen: Dispatch>`
`SetState` function open or close _Tour_
### `setSteps: Dispatch>`
`SetState` function to update the `Array` of steps.
### `meta: string`
Global meta information that could be useful in complex Tour/s situtations
### `setMeta: Dispatch>`
`SetState` function to update the global meta info.
> **Warning**: Make sure you reset the `currentStep` value using the `setCurrentStep` function to ensure the tour will be opened to the correct step after update. Otherwise, in case where a person has already interacted with the tour steps and closed the tours on step 5 for example, they might open to the incorrect step, or similarly if the new set of steps only has 3 steps nothing will open.
## `withTour`
In case you needed there is an enhancer that allows you to have all `useTour` functionalities through a Higher Order Component.
```jsx
import { Component } from 'react'
import { withTour } from '@reactour/tour'
class MyComponent extends Component {
render() {
return (
<>
