React Shepherd

A React wrapper for the site tour library Shepherd

Tour - GuideReact
shepherd-pro/react-shepherdreact-shepherd.vercel.appreact-shepherd

README

react-shepherd


react-shepherd is built and maintained by Ship Shape. Contact us for web app consulting, development, and training for your project.

This is a React wrapper for the Shepherd, site tour, library.
It's mainly a wrapper around the Shepherd library that exposes the tour object and methods to the context object
that can be passed into props for dynamic interactivity.

Install


  1. ```bash
  2. npm install --save react-shepherd
  3. ```

Usage


  1. ```jsx
  2. import React, { Component, useContext } from 'react'
  3. import { ShepherdTour, ShepherdTourContext } from 'react-shepherd'
  4. import newSteps from './steps'

  6. const tourOptions = {
  7.   defaultStepOptions: {
  8.     cancelIcon: {
  9.       enabled: true
  10.     }
  11.   },
  12.   useModalOverlay: true
  13. };

  15. function Button() {
  16.   const tour = useContext(ShepherdTourContext);

  18.   return (
  19.     <button className="button dark" onClick={tour.start}>
  20.       Start Tour
  21.     </button>
  22.   );
  23. }

  25. class App extends Component {
  26.   render() {
  27.     return (
  28.       <div>
  29.         <ShepherdTour steps={newSteps} tourOptions={tourOptions}>
  30.           <Button />
  31.         </ShepherdTour>
  32.       </div>
  33.     );
  34.   }
  35. }
  36. ```

Configuration


The following configuration options for a tour can be set on the ShepherdTour to control the way that Shepherd is used. This is simply a POJO passed to Shepherd to use the options noted in the Shepherd Tour options.
The only required option is steps, which is an array passed to the props.

tourOptions


PropTypes.object
Used to set the options that will be applied to each step by default. You can pass in any of the options that you can with Shepherd.

steps


PropTypes.array
You must pass an array of steps to steps, something like this:

  1. ```js
  2. const steps = [
  3.   {
  4.     id: 'intro',
  5.     attachTo: { element: '.first-element', on: 'bottom' },
  6.     beforeShowPromise: function () {
  7.       return new Promise(function (resolve) {
  8.         setTimeout(function () {
  9.           window.scrollTo(0, 0);
  10.           resolve();
  11.         }, 500);
  12.       });
  13.     },
  14.     buttons: [
  15.       {
  16.         classes: 'shepherd-button-secondary',
  17.         text: 'Exit',
  18.         type: 'cancel'
  19.       },
  20.       {
  21.         classes: 'shepherd-button-primary',
  22.         text: 'Back',
  23.         type: 'back'
  24.       },
  25.       {
  26.         classes: 'shepherd-button-primary',
  27.         text: 'Next',
  28.         type: 'next'
  29.       }
  30.     ],
  31.     classes: 'custom-class-name-1 custom-class-name-2',
  32.     highlightClass: 'highlight',
  33.     scrollTo: false,
  34.     cancelIcon: {
  35.       enabled: true,
  36.     },
  37.     title: 'Welcome to React-Shepherd!',
  38.     text: ['React-Shepherd is a JavaScript library for guiding users through your React app.'],
  39.     when: {
  40.       show: () => {
  41.         console.log('show step');
  42.       },
  43.       hide: () => {
  44.         console.log('hide step');
  45.       }
  46.     }
  47.   },
  48.   // ...
  49. ];
  50. ```

Steps


The options are the same as Shepherd options.

License


MIT