Tourist Guide into your React Components

Demo

## Install ```zsh npm i -S reactour # or yarn add reactour ``` From `v1.9.1` [styled-components](https://www.styled-components.com/) it isn't bundled into the package and is required `styled-components@^4` and `react@^16.3` due to the use of [createRef](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs), so: ```zsh npm i -S styled-components@^4.0.0 # or 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.

#### Silver sponsors 🥈

Dopt gives developers UI components and SDKs to build seamless onboarding and education experiences in minutes.

## 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 */} ) } const steps = [ { selector: '.first-step', content: 'This is my first Step', }, // ... ] ``` ### 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` ```js // example `${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'])` ```js // example ``` #### getCurrentStep > Function triggered each time current step change Type: `func` ```js // example 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` ```js // example Done! Let's start playing} /> ``` #### 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 (document.body.style.overflowY = 'hidden')} /> ``` #### onBeforeClose > Do something before _Tour_ is closed Type: `func` ```js // example (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 ```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 ```js 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 `true` // when `disableInteraction` 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

How is implemented the scroll lock behaviour in the Demo?

To guarantee a cross browser behaviour we use body-scroll-lock.

Import the library

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}
/>

Package	Téléchargements	Stars	Taille	Issues	Publication	Licence

reactour	46,765	3,975	120 kB	81	il y a un an	MIT