Tourist Guide into your React Components

Documentation

https://docs.react.tours

> This documentation is for the latest release, which uses npm scoped package @reactour. The original reactour is now on branch v1 and its documentation can be found here.

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



setIsOpen(true)}>Open Tour

)
}
`

Examples

#### Playground

The Playground is the perfect place to play aroud with all @reactour _Components_. Here is an online version.

#### Sandboxes

- Using React Router
- Using React Router with automatic route switching
- Using React Modal
- Using Semantic UI Modal
- Using React Bootstrap Modal
- Tour with data fetching

![Edit @reactour/tour Demo Template](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

$3

Array of elements to highlight with special info and props.

StepType

#### selector: string | Element

A string containing one CSS Selector 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 to be included (by union) in the highlighted region of the _Mask_.

#### mutationObservables?: string[]

Array of CSS Selector that addition or removal will triggered a rerender of the _Mask_ shape.

#### resizeObservables?: string[]

Array of CSS Selector 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.

$3

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 (
styles={{ badge: (base) => ({ ...base, backgroundColor: 'red' }) }}
>
👉 {children} 👈

)
}

function Close({ onClick }) {
return (
onClick={onClick}
style={{ position: 'absolute', right: 0, top: 0 }}
>
x

)
}

const steps = [
/ ... /
]

export default function App() {
return (

{/ ... /}

)
}
`

$3

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 and Popover docs 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' }),
}
`

$3

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.

$3

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

$3

Function to control the _Tour_ current step state.

$3

Custom _Tour_ current step state.

This option could be overrided on specific steps using stepInteraction prop.

$3

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

$3

The _Tour_ uses FocusScope in order to lock the focus iteration inside the _Popover_ when _Tour_ is active. This prop allows to disable this behaviour.

$3

Disable interactivity with _Dot_ navigation inside _Popover_.

$3

If true, don't show tours when selector or document.getElementById(step.selector) is falsy.

$3

Type details

`ts
type KeyboardParts = 'esc' | 'left' | 'right'
`

Disable all keyboard navigation events when true, disable only selected keys when array.

default: false

$3

Class assigned to _Popover_.

default: reactour__popover

$3

Class assigned to _Mask_.

default: reactour__mask

$3

Class assigned to highlighted part of _Mask_. Useful when using disableInteraction.

$3

$3

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.

$3

Action fired just after the _Tour_ is open.

$3

Action fired just before the _Tour_ is closed.

$3

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.

$3

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.

$3

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
steps={steps}
disableInteraction
onClickHighlighted={(e, clickProps) => {
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
}
`

$3

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
steps={steps}
disableInteraction
keyboardHandler={(e, clickProps) => {
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)
}
}}
>
{/ ... /}

`

$3

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.

$3

Show or hide the _Navigation_ (_Prev_ and _Next_ buttons and _Dots_) inside _Popover_.

$3

Show or hide _Prev_ and _Next_ buttons inside _Popover_.

$3

Show or hide the _Close_ button inside _Popover_.

$3

Show or hide the _Badge_ inside _Popover_.

$3

Show or hide _dots_ navigation inside _Popover_.

$3

Activate smooth scroll behavior when steps are outside viewport.

default: false

$3

Tolerance in pixels to add when calculating if the step element is outside viewport to scroll into view.

$3

Type details

`ts
type A11yOptions = {
ariaLabelledBy: string
closeButtonAriaLabel: string
showNavigationScreenReaders: boolean
}
`

Configure generic accessibility related attributes like aria-labelledby, aria-label for _Close_ button and if show or hide _Dot_ navigation in screen readers.

$3

Option to navigate and show _Navigation_ in right-to-left mode

$3

Mask ID to pass directly into the Mask component

$3

Clip ID to pass directly into the Mask component

$3

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]
`

$3

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}
onClick={() => {
if (isLastStep) {
props.setIsOpen(false)
} else {
props.setCurrentStep((s) => s + 1)
}
}}
>
{isLastStep ? 'x' : '>'}



)
}

const steps = [
/ ... /
]

function App() {
return (
steps={steps}
ContentComponent={ContentComponent}
styles={{ popover: (base) => ({ ...base, padding: 0 }) }}
>
{/ ... /}

)
}
`

$3

Element which wraps the Tour, useful in case is needed to port the Tour into a Portal. 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}

)
}
`

$3

Is the _Tour_ open or close

$3

The current step. zero based

$3

The Array of steps set currently

$3

SetState function open or close _Tour_

$3

SetState function to update the Array of steps.

$3

Global meta information that could be useful in complex Tour/s situtations

$3

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 (
<>
this.props.setIsOpen(true)}>Start Tour


)
}
}

export default withTour(MyCompnent)
``