@insomnia-dev/reactour-emotion

Tourist Guide into your React Components

Demo

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

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

closeButtonAriaLabel

aria-label attribute for the close button (for accessibility)

Type: string

Default: 'Close'

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
3  getCurrentStep={(curr) => console.log(`The current step is ${curr + 1}`)}
4/>

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

steps

Array of elements to highligt 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  'observe': PropTypes.string,
17  'highlightedSelectors': PropTypes.array,
18  'mutationObservables': PropTypes.array,
19  'resizeObservables': PropTypes.array,
20})),

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    // Observe direct children DOM mutations of this node
29    // If a child is added: the highlighted region is redrawn focused on it
30    // If a child is removed: the highlighted region is redrawn focused on the step selector node
31    observe: '[data-tour="observable-parent"]',
32    // Array of selectors, each selected node will be included (by union)
33    // in the highlighted region of the mask. You don't need to add the
34    // step selector here as the default highlighted region is focused on it
35    highlightedSelectors: ['[data-tour="highlighted-element"]'],
36    // Array of selectors, addition/removal of a matching node will trigger a rerender
37    // of the mask shape. Useful in combination with highlightedSelectors when highlighted
38    // region of mask should be redrawn after a user action
39    mutationObservables: ['[data-tour="mutable-element"]'],
40    // Array of selectors, each selected node resize will triggered a rerender of the mask shape.
41    // Useful in combination with highlightedSelectors when highlighted region of mask should
42    // be redrawn after a user action. You should also add the selector in mutationObservables
43    // if you want to track DOM addition/removal too
44    resizeObservables: ['[data-tour="resizable-parent"]'],
45  },
46  // ...
47]

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

disableFocusLock

Disable FocusLock component.

Type: bool

Default: false

FAQ

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

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

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