@nickcis/reactour
v1.19.4
Tourist Guide into your React Components
0/weekUpdated 10 months agoMITUnpacked: 124.1 KB
Published by Lionel T
Tourist Guide into your React Components
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
Sponsored by
#### 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.
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
#### 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
// 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`
FAQ
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}
/>