Tourist Guide into your React Components

Demo

⚠️ The master branch is currently in development. Please use the v1 branch to follow the current versions published.

Install

1npm i -S reactour
2# or
3yarn 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:

1npm i -S styled-components@^4.0.0
2# or
3yarn 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.

1import React from 'react'
2import Tour from 'reactour'
3
4class App extends Component {
5  // ...
6
7  render  (
8    <>
9      { /* other stuff */}
10      <Tour
11        steps={steps}
12        isOpen={this.state.isTourOpen}
13        onRequestClose={this.closeTour} />
14    </>
15  )
16}
17
18const steps = [
19  {
20    selector: '.first-step',
21    content: 'This is my first Step',
22  },
23  // ...
24]

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

accessibilityOptions

Configure accessibility related accessibility options

Type: object

Default:

1    // attribute to associate the dialog with a title for screen readers
2    ariaLabelledBy: null,
3    // aria-label attribute for the close button
4    closeButtonAriaLabel: 'Close',
5    // Show/Hide Navigation Dots for screen reader software
6    showNavigationScreenReaders: true,

badgeContent

Customize Badge content using current and total steps values

Type: func

1// example
2<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

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'])

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

getCurrentStep

Function triggered each time current step change

Type: func

1// example
2<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

1// example
2<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

Type: func

onAfterOpen

Do something after Tour is opened

Type: func

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

onBeforeClose

Do something before Tour is closed

Type: func

1// example
2<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

Type: func

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

Default: 0

steps

Array of elements to highlight with special info and props

Type: shape

Required: true

Steps shape

1steps: PropTypes.arrayOf(PropTypes.shape({
2  'selector': PropTypes.string,
3  'content': PropTypes.oneOfType([
4    PropTypes.node,
5    PropTypes.element,
6    PropTypes.func,
7  ]).isRequired,
8  'position':PropTypes.oneOfType([
9    PropTypes.arrayOf(PropTypes.number),
10    PropTypes.oneOf(['top', 'right', 'bottom', 'left', 'center']),
11  ]),
12  'action': PropTypes.func,
13  'style': PropTypes.object,
14  'stepInteraction': PropTypes.bool,
15  'navDotAriaLabel': PropTypes.string,
16})),

Steps example

1const steps = [
2  {
3    selector: '[data-tour="my-first-step"]',
4    content: ({ goTo, inDOM }) => (
5      <div>
6        Lorem ipsum <button onClick={() => goTo(4)}>Go to Step 5</button>
7        <br />
8        {inDOM && '🎉 Look at your step!'}
9      </div>
10    ),
11    position: 'top',
12    // you could do something like:
13    // position: [160, 250],
14    action: node => {
15      // by using this, focus trap is temporary disabled
16      node.focus()
17      console.log('yup, the target element is also focused!')
18    },
19    style: {
20      backgroundColor: '#bada55',
21    },
22    // Disable interaction for this specific step.
23    // Could be enabled passing `true`
24    // when `disableInteraction` prop is present in Tour
25    stepInteraction: false,
26    // Text read to screen reader software for this step's navigation dot
27    navDotAriaLabel: 'Go to step 4',
28  },
29  // ...
30]

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

FAQ

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

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

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