reactour-gcb

Tourist Guide into your React Components

Demo

This is a fork from elrumordelaluz/reactour. I've added a few additional features including 1) Pre and post action methods (credit to SacredSkull) 2) Add waitSec to steps to allow some delay if the component isn't rendered when the step is reached. These changes are also up for PR on elrumordelaluz/reactour and I will deprecate this project if elrumordelaluz/reactour gets these changes on his branch.

Install

npm i -S reactour
# or
yarn add reactour

From v1.9.1 styled-components it isn't bundled into the package and is required styled-components@^4 and react@^16.3 due to the use of createRef, so:

npm i -S styled-components@^4.0.0
# or
yarn add styled-components@^4.0.0

Usage

Add the Tour Component in your Application, passing the steps with the elements to highlight during the Tour.

import React from 'react'
import Tour from 'reactour'

class App extends Component {
  // ...

  render  (
    <>
      { /* other stuff */}
      <Tour
        steps={steps}
        isOpen={this.state.isTourOpen}
        onRequestClose={this.closeTour} />
    </>
  )
}

const steps = [
  {
    selector: '.first-step',
    content: 'This is my first Step',
  },
  // ...
]

Tour Props

accentColor

Change --reactour-accent (defaults to accentColor on IE) css custom prop to apply color in Helper, number, dots, etc

Type: string

Default: #007aff

badgeContent

Customize Badge content using current and total steps values

Type: func

// example
<Tour badgeContent={(curr, tot) => `${curr} of ${tot}`} />

children

Content to be rendered inside the Helper

Type: node | elem

className

Custom class name to add to the Helper

Type: string

closeWithMask

Close the Tour by clicking the Mask

Type: bool

Default: true

deterministic

If jumping between steps (e.g. with dots) should we attempt to execute all preAction/action/postAction (or rewind) handlers in between? The element of each step (step.selector) is parsed and passed to each function, but may not be completely accurate, due to the fact that each step has to be replayed quickly - some UI elements may not respond quickly enough.

Type: bool

Default: true

disableDotsNavigation

Disable interactivity with Dots navigation in Helper

Type: bool

disableInteraction

Disable the ability to click or intercat in any way with the Highlighted element

Type: bool

disableKeyboardNavigation

Disable all keyboard navigation (next and prev step) when true, disable only selected keys when array

Type: bool | array(['esc', 'right', 'left'])

// example
<Tour disableKeyboardNavigation={['esc']} />

getCurrentStep

Function triggered each time current step change

Type: func

// example
<Tour getCurrentStep={curr => console.log(`The current step is ${curr + 1}`)} />

goToStep

Programmatically change current step after the first render, when the value changes

Type: number

highlightedMaskClassName

Custom class name to add to the element which is the overlay for the target element when disableInteraction

Type: string

inViewThreshold

Tolerance in pixels to add when calculating if an element is outside viewport to scroll into view

Type: number

isOpen

You know…

Type: bool

Required: true

lastStepNextButton

Change Next button in last step into a custom button to close the Tour

Type: node

// example
<Tour lastStepNextButton={<MyButton>Done! Let's start playing</MyButton>} />

maskClassName

Custom class name to add to the Mask

Type: string

maskSpace

Extra Space between in pixels between Highlighted element and Mask

Type: number

Default: 10

nextButton

Renders as next button navigation

Type: node

nextStep

Overrides default nextStep internal function. Gets passed the default nextStep handler as a parameter, so you can choose to execute it based on a requirement. Strange behaviour is expected if you change the current step then also execute the default implementation!

Type: func

<Tour prevStep={(defaultNext) => someRequirement && defaultNext()} />

onAfterOpen

Do something after Tour is opened

Type: func

// example
<Tour onAfterOpen={target => (document.body.style.overflowY = 'hidden')} />

onBeforeClose

Do something before Tour is closed

Type: func

// example
<Tour onBeforeClose={target => (document.body.style.overflowY = 'auto')} />

onRequestClose

Function to close the Tour

Type: func

Required: true

prevButton

Renders as prev button navigation

Type: node

prevStep

Overrides default prevStep internal function. Gets passed the default prevStep handler as a parameter, so you can choose to execute it based on a requirement. Strange behaviour is expected if you change the current step then also execute the default implementation!

Type: func

<Tour prevStep={(defaultPrev) => someRequirement && defaultPrev()} />

rounded

Beautify Helper and Mask with border-radius (in px)

Type: number

Default: 0

scrollDuration

Smooth scroll duration when positioning the target element (in ms)

Type: number

Default: 1

scrollOffset

Offset when positioning the target element after scroll to it

Type: number

Default: a calculation to the center of the viewport

showButtons

Show/Hide Helper Navigation buttons

Type: bool

Default: true

showCloseButton

Show/Hide Helper Close button

Type: bool

Default: true

showNavigation

Show/Hide Helper Navigation Dots

Type: bool

Default: true

showNavigationNumber

Show/Hide number when hovers on each Navigation Dot

Type: bool

Default: true

showNumber

Show/Hide Helper Number Badge

Type: bool

Default: true

startAt

Starting step when Tour is open the first time

Type: number

steps

Array of elements to highlight with special info and props

Type: shape

Required: true

Steps shape

steps: PropTypes.arrayOf(PropTypes.shape({
  'selector': PropTypes.string,
  'content': PropTypes.oneOfType([
    PropTypes.node,
    PropTypes.element,
    PropTypes.func,
  ]).isRequired,
  'position':PropTypes.oneOfType([
    PropTypes.arrayOf(PropTypes.number),
    PropTypes.oneOf(['top', 'right', 'bottom', 'left', 'center']),
  ]),
  'action': PropTypes.func,
  'waitSec': PropTypes.number,
  'style': PropTypes.object,
  'stepInteraction': PropTypes.bool,
  'preAction': propTypes.func,
  'postAction': propTypes.func,
  'rewindAction': propTypes.func
})),

Steps example

const steps = [
  {
    selector: '[data-tour="my-first-step"]',
    content: ({ goTo, inDOM }) => (
      <div>
        Lorem ipsum <button onClick={() => goTo(4)}>Go to Step 5</button>
        <br />
        {inDOM && '🎉 Look at your step!'}
      </div>
    ),
    position: 'top',
    // you could do something like:
    // position: [160, 250],
    action: node => {
      // by using this, focus trap is temporary disabled
      node.focus()
      console.log('yup, the target element is also focused!')
    },
    waitSec: 5, //Allow 5 seconds for the content to appear before giving up
    style: {
      backgroundColor: '#bada55',
    },
    // Disable interaction for this specific step.
    // Could be enabled passing `true`
    // when `disableInteraction` prop is present in Tour
    stepInteraction: false,
    preAction: () => {
        // this is executed before this step starts
        // preActions will NOT run if used on the first step
        console.log("Step is about to start")
    },
    postAction: () => {
        // this is executed before this step ends
        // postActions will NOT run if used on the last step
        console.log("Step is about to finish")
    }
  },
  // ...
]

update

Value to listen if a forced update is needed

Type: string

updateDelay

Delay time when forcing update. Useful when there are known animation/transitions

Type: number

Default: 1

Step props

content

The content of the step, which can be simple text, a node, element or a function that returns any of these.

Type: node|element|func

Required: true

observe

Watches an element for changes and updates the spotlight accordingly

Type: node

position

Where the step modal will appear relative to the selected element.

Type: func

action

Action handler that is executed after this step executes.

Type: func

Parameters: node

Resolves step.selector as a node (with document.querySelector) and passed to this handler.

preAction

Action handler that is executed before this step executes.

Type: func

Parameters: node

See action

postAction

Action handler that is executed after this step executes.

Type: func

Parameters: node

See action

rewindAction

Action handler that is executed if this step is rewinded (for resetting)

Type: func

Parameters: node

This performs the same role as the parameter for preAction, Action and postAction, but as the step is backwards, this may not be as reliable.

selector

This string is used with document.querySelector to select the element for this step.

Type: string

stepInteraction

Disables interaction only for this step, rather than needing to enable it globally with disableInteraction.

Type: func

style

CSS/style to be applied to this step only. Pass as an object (or inline CSS).

Type: object

FAQ

How is the scroll lock behaviour implemented in the Demo?

To guarantee a cross browser behaviour we use body-scroll-lock.

Import the library

import { disableBodyScroll, enableBodyScroll } from 'body-scroll-lock'

Create the event handlers

disableBody = target => disableBodyScroll(target)
enableBody = target => enableBodyScroll(target)

Then assign them into the Tour props

<Tour
  {...props}
  onAfterOpen={this.disableBody}
  onBeforeClose={this.enableBody}
/>

Why should I use pre instead of post? I can just use post in the step before (and vice versa).

In many cases, choosing between the pre & post action will not matter to the actual tour. They are mainly there to logically separate actions for the programmer.

Look at the example below to see an example of where this might help writing steps.

The bad version:

[
{
selector: '#modal',
content: 'Here you can enter data'
postAction: () => openTheDropdown()
},
{
selector: '#the-dropdown',
content: 'Here is the dropdown'
},
]

This works, but why should the modal step care about the dropdown? In this case, the preAction handler makes more sense.

The better version:

[
{
selector: '#modal',
content: 'Here you can enter data'
},
{
selector: '#the-dropdown',
content: 'Here is the dropdown',
preAction: () => openTheDropdown()
},
]

Now if you have a lot of tour steps, each step is well separated in scope.