Tourist Guide into your React Components
npm install reactour
Tourist Guide into your React Components
``zsh`
npm i -S reactouror
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:
`zsh`
npm i -S styled-components@^4.0.0or
yarn add styled-components@^4.0.0
#### Gold sponsors 🥇
Reactour is proud to be sponsored by Frigade, a developer tool for building better product onboarding: guided tours, getting started checklists, announcements, and more.
#### Silver sponsors 🥈
Dopt gives developers UI components and SDKs to build seamless onboarding and education experiences in minutes.
Add the Tour Component in your Application, passing the steps with the elements to highlight during the _Tour_.
`js
import React from 'react'
import Tour from 'reactour'
class App extends Component {
// ...
render (
<>
{ / other stuff /}
isOpen={this.state.isTourOpen}
onRequestClose={this.closeTour} />
>
)
}
const steps = [
{
selector: '.first-step',
content: 'This is my first Step',
},
// ...
]
`
#### 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
`js${curr} of ${tot}
// example} />`
#### 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'])
`js`
// example
#### getCurrentStep
> Function triggered each time current step change
Type: func
`jsThe current step is ${curr + 1}
// example)}`
/>
#### 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
`js`
// example
#### 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
`js`
// example
#### onBeforeClose
> Do something before _Tour_ is closed
Type: func
`js`
// example
#### 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
`js`
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,
'style': PropTypes.object,
'stepInteraction': PropTypes.bool,
'navDotAriaLabel': PropTypes.string,
'observe': PropTypes.string,
'highlightedSelectors': PropTypes.array,
'mutationObservables': PropTypes.array,
'resizeObservables': PropTypes.array,
})),
##### Steps example
`jstrue
const steps = [
{
selector: '[data-tour="my-first-step"]',
content: ({ goTo, inDOM }) => (
Lorem ipsum
{inDOM && '🎉 Look at your step!'}
),
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!')
},
style: {
backgroundColor: '#bada55',
},
// Disable interaction for this specific step.
// Could be enabled passing disableInteraction
// when prop is present in Tour`
stepInteraction: false,
// Text read to screen reader software for this step's navigation dot
navDotAriaLabel: 'Go to step 4',
// Observe direct children DOM mutations of this node
// If a child is added: the highlighted region is redrawn focused on it
// If a child is removed: the highlighted region is redrawn focused on the step selector node
observe: '[data-tour="observable-parent"]',
// Array of selectors, each selected node will be included (by union)
// in the highlighted region of the mask. You don't need to add the
// step selector here as the default highlighted region is focused on it
highlightedSelectors: ['[data-tour="highlighted-element"]'],
// Array of selectors, addition/removal of a matching node will trigger a rerender
// of the mask shape. Useful in combination with highlightedSelectors when highlighted
// region of mask should be redrawn after a user action
mutationObservables: ['[data-tour="mutable-element"]'],
// Array of selectors, each selected node resize will triggered a rerender of the mask shape.
// Useful in combination with highlightedSelectors when highlighted region of mask should
// be redrawn after a user action. You should also add the selector in mutationObservables
// if you want to track DOM addition/removal too
resizeObservables: ['[data-tour="resizable-parent"]'],
},
// ...
]
#### 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`
Import the library
How is implemented the scroll lock behaviour in the Demo?
To guarantee a cross browser behaviour we use body-scroll-lock.
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}
/>