reactour2
v1.0.3
Tourist Guide into your React Components. This is a fork of reactour. It includes some improvements not yet in reactour including pre/post action functions and optinal dealy to wait for components to render.
0/weekUpdated 3 years agoMITUnpacked: 103.8 KB
Published by Robert G
npm install reactour2
Tourist Guide into your React Components
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
``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
Usage
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',
},
// ...
]
`
$3
#### 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
#### 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'])
`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. 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
`js`
#### 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. 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
`js`
#### 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
`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,
'waitSec': PropTypes.number,
'style': PropTypes.object,
'stepInteraction': PropTypes.bool,
'preAction': propTypes.func,
'postAction': propTypes.func,
'rewindAction': propTypes.func
})),
##### 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!')
},
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
// when 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
$3
#### 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
Import the library
How is the scroll lock behaviour implemented 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}
/>The bad version: The better version:
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.
[
{
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.
[
{
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.