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

1npm i -S @reactour/tour
2# or
3yarn add @reactour/tour

Usage

Add the TourProvider at the root of your Application, passing the steps of the elements to highlight during the Tour.

1// ...
2import { TourProvider } from '@reactour/tour'
3
4ReactDOM.render(
5  <TourProvider steps={steps}>
6    <App />
7  </TourProvider>,
8  document.getElementById('root')
9)
10
11const steps = [
12  {
13    selector: '.first-step',
14    content: 'This is my first Step',
15  },
16  // ...
17]

Then somewhere down the Application tree, control the Tour using useTour hook.

1import { useTour } from '@reactour/tour'
2
3function App() {
4  const { setIsOpen } = useTour()
5  return (
6    <>
7      <p className="first-step">
8        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at
9        finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta
10        metus nec, porta luctus orci
11      </p>
12      <button onClick={() => setIsOpen(true)}>Open Tour</button>
13    </>
14  )
15}

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

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.

components?: PopoverComponentsType

Prop to customize granurally each Component inside the Popover.

Components available

1import { components } from '@reactour/tour'
2
3function Badge({ children }) {
4  return (
5    <components.Badge
6      styles={{ badge: (base) => ({ ...base, backgroundColor: 'red' }) }}
7    >
8      👉 {children} 👈
9    </components.Badge>
10  )
11}
12
13function Close({ onClick }) {
14  return (
15    <button
16      onClick={onClick}
17      style={{ position: 'absolute', right: 0, top: 0 }}
18    >
19      x
20    </button>
21  )
22}
23
24const steps = [
25  /* ... */
26]
27
28export default function App() {
29  return (
30    <TourProvider steps={steps} components={{ Badge, Close }}>
31      {/* ... */}
32    </TourProvider>
33  )
34}

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 and Popover docs for its specific Components

Tour Components

1const styles = {
2  maskWrapper: (base) => ({
3    ...base,
4    color: 'red',
5  }),
6  highlightedArea: (base, { x, y }) => ({
7    ...base,
8    x: x + 10,
9    y: y + 10,
10  }),
11  badge: (base) => ({ ...base, color: 'blue' }),
12}

padding?: Padding

1type Padding =
2  | number
3  | {
4      mask?: ComponentPadding
5      popover?: ComponentPadding
6      wrapper?: ComponentPadding
7    }
8
9// x and y same value or [x, y] or [top, x, bottom] or [top, right, bottom, left]
10type 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

1type Position =
2  | 'top'
3  | 'right'
4  | 'bottom'
5  | 'left'
6  | 'center'
7  | [number, number]
8  | ((postionsProps: PositionProps) => Position)
9
10type PositionProps = {
11  bottom: number
12  height: number
13  left: number
14  right: number
15  top: number
16  width: number
17  windowWidth: number
18  windowHeight: number
19}

Set a global position for the Popover in all steps, fixed in case of [number, number], calculated in case of position string

setCurrentStep: Dispatch<React.SetStateAction<number>>

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

disableInteraction?: boolean | ((clickProps: Pick<ClickProps, 'currentStep' | 'steps' | 'meta'>) => 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 prop.

disableFocusLock?: boolean

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.

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

1type KeyboardParts = 'esc' | 'left' | 'right'

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

default: false

className?: string

Class assigned to Popover.

default: reactour__popover

maskClassName?: string

Class assigned to Mask.

default: reactour__mask

highlightedMaskClassName?: string

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

nextButton?: (props: BtnFnProps) => void

prevButton?: (props: BtnFnProps) => void

1type BtnFnProps = {
2  Button: React.FC<NavButtonProps>
3  setCurrentStep: Dispatch<React.SetStateAction<number>>
4  stepsLength: number
5  currentStep: number
6  setIsOpen: Dispatch<React.SetStateAction<boolean>>
7}
8
9type NavButtonProps = {
10  onClick?: () => void
11  kind?: 'next' | 'prev'
12  hideArrow?: boolean
13}

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

1type ClickProps = {
2  setIsOpen: Dispatch<React.SetStateAction<boolean>>
3  setCurrentStep: Dispatch<React.SetStateAction<number>>
4  setSteps: Dispatch<React.SetStateAction<StepType[]>>
5  setMeta: Dispatch<React.SetStateAction<string>>
6  currentStep: number
7  steps: StepType[]
8  meta: string
9}

Function that overrides the default close behavior of the Mask click handler. Comes with useful parameters to play with.

onClickClose?: (clickProps: ClickProps) => void

1type ClickProps = {
2  setIsOpen: Dispatch<React.SetStateAction<boolean>>
3  setCurrentStep: Dispatch<React.SetStateAction<number>>
4  setSteps: Dispatch<React.SetStateAction<StepType[]>>
5  setMeta: Dispatch<React.SetStateAction<string>>
6  currentStep: number
7  steps: StepType[]
8  meta: string
9}

Function that overrides the default close behavior of the Close icon click handler. Comes with useful parameters to play with.

onClickHighlighted?: (e: MouseEventHandler<SVGRectElement>, 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.

1<TourProvider
2  steps={steps}
3  disableInteraction
4  onClickHighlighted={(e, clickProps) => {
5    console.log('No interaction at all')
6    if (clickProps.currentStep < 2) {
7      e.stopPropagation()
8      event.preventDefault()
9      clickProps.setCurrentStep(
10        Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
11      )
12    }
13  }}
14>
15  {/* ... */}
16</TourProvider>

1type ClickProps = {
2  setIsOpen: Dispatch<React.SetStateAction<boolean>>
3  setCurrentStep: Dispatch<React.SetStateAction<number>>
4  setSteps: Dispatch<React.SetStateAction<StepType[]>>
5  setMeta: Dispatch<React.SetStateAction<string>>
6  currentStep: number
7  steps: StepType[]
8  meta: string
9}

keyboardHandler?: KeyboardHandler

Function to handle keyboard events in a custom way.

1type KeyboardHandler = {
2  keyboardHandler?: (
3    e: KeyboardEvent,
4    clickProps?: ClickProps,
5    status?: {
6      isEscDisabled?: boolean
7      isRightDisabled?: boolean
8      isLeftDisabled?: boolean
9    }
10  ) => void
11}

1<TourProvider
2  steps={steps}
3  disableInteraction
4  keyboardHandler={(e, clickProps) => {
5    if (e.key === 'ArrowRight') {
6      clickProps.setCurrentStep(
7        Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
8      )
9    }
10    if (e.key === 'ArrowLeft') {
11      clickProps.setCurrentStep(Math.max(clickProps.currentStep - 1, 0))
12    }
13    if (e.key === 'Escape') {
14      const nextStep = Math.floor(Math.random() * clickProps.steps.length)
15      clickProps.setCurrentStep(nextStep)
16    }
17  }}
18>
19  {/* ... */}
20</TourProvider>

badgeContent?: (badgeProps: BadgeProps) => any

1type BadgeProps = {
2  totalSteps: number
3  currentStep: number
4  transition: boolean
5}

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

1type A11yOptions = {
2  ariaLabelledBy: string
3  closeButtonAriaLabel: string
4  showNavigationScreenReaders: boolean
5}

Configure generic accessibility related attributes like aria-labelledby, aria-label 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

clipId?: string

Clip ID to pass directly into the Mask component

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

1type PositionType = (
2  postionsProps: PositionProps,
3  prev: RectResult
4) => 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]

ContentComponent?: ComponentType<PopoverContentProps>

Completelly custom component to render inside the Popover.

1type PopoverContentProps = {
2  styles?: StylesObj & PopoverStylesObj & MaskStylesObj
3  badgeContent?: (badgeProps: BadgeProps) => any
4  components?: PopoverComponentsType
5  accessibilityOptions?: A11yOptions
6  disabledActions?: boolean
7  onClickClose?: (clickProps: ClickProps) => void
8  setCurrentStep: Dispatch<React.SetStateAction<number>>
9  currentStep: number
10  transition?: boolean
11  isHighlightingObserved?: boolean
12  setIsOpen: Dispatch<React.SetStateAction<boolean>>
13  steps: StepType[]
14  showNavigation?: boolean
15  showPrevNextButtons?: boolean
16  showCloseButton?: boolean
17  showBadge?: boolean
18  nextButton?: (props: BtnFnProps) => void
19  prevButton?: (props: BtnFnProps) => void
20  disableDotsNavigation?: boolean
21  rtl?: boolean
22}

1function ContentComponent(props) {
2  const isLastStep = props.currentStep === props.steps.length - 1
3  const content = props.steps[props.currentStep].content
4  return (
5    <div style={{ border: '5px solid red', padding: 10, background: 'white' }}>
6      {/* Check if the step.content is a function or a string */}
7      {typeof content === 'function'
8        ? content({ ...props, someOtherStuff: 'Custom Text' })
9        : content}
10      <button
11        onClick={() => {
12          if (isLastStep) {
13            props.setIsOpen(false)
14          } else {
15            props.setCurrentStep((s) => s + 1)
16          }
17        }}
18      >
19        {isLastStep ? 'x' : '>'}
20      </button>
21    </div>
22  )
23}
24
25const steps = [
26  /* ... */
27]
28
29function App() {
30  return (
31    <TourProvider
32      steps={steps}
33      ContentComponent={ContentComponent}
34      styles={{ popover: (base) => ({ ...base, padding: 0 }) }}
35    >
36      {/* ... */}
37    </TourProvider>
38  )
39}

Wrapper?: ComponentType

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

1import { useTour } from '@reactour/tour'
2
3function MyComponent() {
4  const { isOpen, currentStep, steps, setIsOpen, setCurrentStep, setSteps } = useTour()
5  return (
6    <>
7      <h1>{isOpen ? 'Welcome to the tour!' : 'Thank you for participate!'}</h1>
8      <p>
9        Now you are visiting the place {currentStep + 1} of {steps.length}
10      </p>
11      <nav>
12        <button onClick={() => setIsOpen(o => !o)}>Toggle Tour</button>
13        <button onClick={() => setCurrentStep(3)}>
14          Take a fast way to 4th place
15        </button>
16        <button
17          onClick={() =>
18            setSteps([              { selector: '.new-place-1', content: 'New place 1' },              { selector: '.new-place-2', content: 'New place 2' },            ])
19            setCurrentStep(1)
20          }
21        >
22          Switch to a new set of places, starting from the last one!
23        </button>
24      </nav>
25    </>
26  )
27}

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<React.SetStateAction<boolean>>

SetState function open or close Tour

setSteps: Dispatch<React.SetStateAction<StepType[]>>

SetState function to update the Array of steps.

meta: string

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

setMeta: Dispatch<React.SetStateAction<string>>

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.

1import { Component } from 'react'
2import { withTour } from '@reactour/tour'
3
4class MyComponent extends Component {
5  render() {
6    return (
7      <>
8        <button onClick={() => this.props.setIsOpen(true)}>Start Tour</button>
9        <div>{/* ... */}</div>
10      </>
11    )
12  }
13}
14
15export default withTour(MyCompnent)