Responsive Guided App Tour In JavaScript – shepherd

Preview:

Description:

shepherd is a JavaScript library that creates an interactive, accessible, dynamic visual guide to let your users learn about new features and functions on your web app.

Full responsive, user-friendly and mobile compatible.

See also:

• 10 Best Guided Tour JavaScript Plugins For Your App

How to use it:

Install the package.

# Yarn
$ yarn add shepherd.js

# NPM
$ npm install shepherd.js --save

Import the shepherd module.

import Shepherd from 'shepherd.js';

Or import the shepherd.js into the document.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/shepherd.min.js"></script>

Create a new tour.

let myTour = new Shepherd.Tour({
    // options here
});

Add steps to the tour.

myTour.addStep({
  id: 'target-element 1',
  title: 'Step 1',
  text: 'This is Step 1',
  attachTo: { 
    element: '.example-css-selector', 
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Next',
      action: tour.next
    }
  ]
});

Start the tour.

myTour.start();

All default tour options.

let myTour = new Shepherd.Tour({

    // Default options for Steps, created through 'addStep'
    defaultStepOptions: {},

    // An array of steps
    steps: [],

    // An optional "name" for the tour. This will be appended to the the tour's dynamically generated `id` property -- which is also set on the `body` element as the `data-shepherd-active-tour` attribute whenever the tour becomes active.
    tourName: '',

    // Whether or not steps should be placed above a darkened modal overlay. 
    // If true, the overlay will create an opening around the target element so that it can remain interactive
    useModalOverlay: true,

    // Specify container element for the modal
    modalContainer: '',

    // An optional container element for the steps.
    stepsContainer: document.body,

    // Exiting the tour with the escape key will be enabled unless this is explicitly set to false.
    exitOnEsc: true or false,

    // Navigating the tour via left and right arrow keys will be enabled unless this is explicitly set to false.
    keyboardNavigation: true of false,

    // If true, will issue a window.confirm before cancelling
    confirmCancel: false,

    // The message to display in the confirm dialog
    confirmCancelMessage: ''
    
})

All default step options.

myTour.addStep({

  // element ID for the step
  id: '',

  // The text in the body of the step. It can be one of four types:
  // HTML string
  // Array of HTML strings
  // HTMLElement object
  // Function to be executed when the step is built. It must return one the three options above.
  text: '',
  
  // Step title
  title: '',

  // where to attach the step to
  attachTo: { 
    element: '.example-css-selector', 
    on: 'bottom'
  },

  // returns a promise. When the promise resolves, the rest of the show code for the step will execute.
  beforeShowPromise: function (){},

  // allows to click target
  canClickTarget: true,

  // extra classes
  classes: '',

  // an array of buttons to add to the step. 
  buttons: [{
    text: '',
    classes: '',
    secondary: false, // adds secondary button
    action: function (){},
    events: {'mouseover': function(){}},
  }],

  // An action on the page which should advance shepherd to the next step. 
  // It can be of the form "selector event", or an object with those properties. 
  // For example: ".some-element click", or {selector: '.some-element', event: 'click'}. 
  // It doesn't have to be an event inside the tour, it can be any event fired on any element on the page. 
  // You can also always manually advance the Tour by calling myTour.next().
  advanceOn: '',

  // extra class to apply to the attachTo element when it is highlighted
  highlightClass: '',

  // shows cancel link
  cancelIcon: true or false

  // scrolls the page to the current step
  scrollTo: true or false

  // a function that lets you override the default scrollTo behavior and define a custom action to do the scrolling, and possibly other logic
  scrollToHandler: function(){},

  // you can define show, hide, etc events inside when
  when: {},

  // a function that, when it returns true, will show the step. If it returns false, the step will be skipped
  showOn: function(){}
  
});

Tour’s API.

// Methods
myTour.addStep(id, options)
myTour.addSteps(steps)
myTour.getById(id)
myTour.next()
myTour.back()
myTour.cancel()
myTour.hide()
myTour.show([id])
myTour.start()
myTour.getCurrentStep()
myTour.on(eventName, handler, [context])
myTour.off(eventName, [handler])
myTour.once(eventName, handler, [context])

// Events
myTour.on('start', function(){
  // ...
})

myTour.on('show', function(){
  // ...
})

myTour.on('hide', function(){
  // ...
})

myTour.on('cancel', function(){
  // ...
})

myTour.on('complete', function(){
  // ...
})

Step’s API.

// Methods
myStep.show()
myStep.hide()
myStep.cancel()
myStep.complete()
myStep.scrollTo()
myStep.isOpen()
myStep.destroy()
myStep.on(eventName, handler, [context])
myStep.off(eventName, [handler])
myStep.once(eventName, handler, [context])

// Events
myStep.on('destroy', function(){
  // ...
})

myStep.on('show', function(){
  // ...
})

myStep.on('hide', function(){
  // ...
})

myTour.on('cancel', function(){
  // ...
})

myTour.on('complete', function(){
  // ...
})

myTour.on('before-hide', function(){
  // ...
})

myTour.on('before-show', function(){
  // ...
})

Changelog:

v8.3.1 (05/07/2021)

• Add preventOverflow option for tether to false

v8.3.0 (04/06/2021)

• Updated package

v8.2.3 (03/26/2021)

• Updated package

v8.2.1 (03/24/2021)

• Update

v8.2.0 (03/03/2021)

• Remove shepherd-target-click-disabled class on step hide
• Bug Fix: properly handle centered modal

v8.1.0 (10/05/2020)

• Add stepsContainer option, allowing users to specify rendering target for step elements
• Add missing types for Step.options and Tour.steps
• Added default fallback for target when step is hidden/destroyed
• shift + tab handled

v8.0.2 (07/10/2020)

• Updated

v8.0.0 (05/26/2020)

• Officially drop IE 11 and remove from browserslist
• Require attachTo.on to show arrow

v7.2.1 (05/14/2020)

• Update

v7.1.6 (05/12/2020)

• Add deepmerge for deep clone functionality

v7.1.5 (04/28/2020)

• Refactor popper options

v7.1.4 (04/24/2020)

• Fixed Layout error when has popperOptions

v7.1.3 (04/23/2020)

• Fix defaultStepOptions.popperOptions issues

v7.1.2 (04/19/2020)

• Update

v7.1.1 (04/14/2020)

• Add new function for creating modals when needed and cleanup

v7.1.0 (03/28/2020)

• Bugfix

v7.0.4 (03/08/2020)

• Single argument on classList.add for IE11 compatibility

v7.0.2 (03/06/2020)

• Fix bug when modifiers was not defined

v7.0.1 (02/25/2020)

• Bugfixes and update.

v6.0.2 (11/09/2019)

• Fix dynamic shepherd classes interfering with tether classes

v6.0.2 (11/09/2019)

• Fix dynamic shepherd classes interfering with tether classes

v6.0.1 (11/07/2019)

• Update

v6.0.0 stable (10/30/2019)

• Dynamically update text while in tour
• Add fade-in animation to tether
• Fixed Step arrow not attaching correctly.
• Remove pinned arrows
• Update transitions on shepherd element
• Removed unnecessary parenthetical commas

v6.0.2beta (10/22/2019)

• Updated

v6.0.0 (10/04/2019)

• Fixed Can’t get shepherdElementZIndex to work

v5.0.1 (08/29/2019)

• Fixed Can’t get shepherdElementZIndex to work
• Fixed Pass shepherdElementZIndex to tippy as zIndex

v5.0.0 (08/26/2019)

• fixed: ionic element – bubbles not pointing to right place due to clientHeight = 0
• added: Vue.js wrapper

v5.0.0beta2 (08/23/2019)

• showCancelLink -> cancelIcon
• Remove link styles
• Remove Shepherd.Evented
• Types don’t support activeTour or Evented properties.
• Remove object-assign-deep, refactor setting popper options
• Use requestAnimationFrame to position modal opening
• Add overlayOpacity to styleVariables options
• Add keyboardNav and exitOnEsc options
• Move activeTour to namespace
• Fixed advanceOn click doesn’t work on nested elements
• Fixed Use currentTarget for advanceOn
• adding alt and role to img element
• fixing a11y issue by adding lang attribute to html element

v4.6.0 (08/10/2019)

• Wrong type definition for scrollTo
• Fade in modal overlay
• Fix for the wrong type definition of StepOptions.scrollTo

v4.5.0 (08/09/2019)

• Support passing elements for text

v4.4.1 (08/08/2019)

• Use objectAssignDeep to deeply merge tippyOptions

v4.4.0 (08/07/2019)

• Fixed Shepherd.Tour constructor definition of steps errors with showOn being undefined

v4.3.4 (08/05/2019)

• Add addSteps method and allow passing steps to tour constructor

v4.3.3 (08/03/2019)

• Bugfix

v4.3.0 (08/02/2019)

• Add option to specify container element for the modal
• Fix cancel link color for when the header has dark background
• Fix content border radius
• Fix applying tippyOptions

v4.2.0 (08/01/2019)

• Remove shepherdElementWidth option

v4.1.0 (07/31/2019)

• Make cancel link more accessible

v4.0.0 stable (07/30/2019)

• major update

v4.0.0beta15 (07/27/2019)

• Switch modals from ids to classes and prefix them

v4.0.0beta14 (07/27/2019)

• Simplify addStep API

v4.0.0beta13 (07/27/2019)

• Remove predefined themes
• Fixed: ommiting ‘on’ doesn’t work
• Fixed: Modal mask opening shows back up on scroll

v4.0.0beta12 (07/27/2019)

• Add first class support for secondary button
• Fixed for IE 11

v4.0.0beta10 (07/21/2019)

• Use autoBind, pass context rather than manually binding
• Polyfill all usage with core-js
• Remove drop util
• Start fixing IE11 support

v4.0.0beta2 (07/14/2019)

• Remove array support for step.options.text
• Cleanup public/private API

v4.0.0beta (07/03/2019)

• .shepherd-popper -> .shepherd, move .shepherd-has-title
• Tippy v5
• Remove remaining lodash, IE 11+
• Remove the string option for advanceOn in favor of object
• Remove string option for attachTo in favor of object
• Fixed bugs: useModalOverlay does not play well with multiple instances on the page

v3.1.0 (06/25/2019)

• Fix jumpy disableScroll
• Reuse existing modal overlay

v3.0.0 (06/24/2019)

• Remove ul, li button wrapper
• Support to keyboard navigation
• Add disableScroll option
• Add aria-describedby and aria-labeledby
• Arrow nav
• Add focus trap, to disallow tabbing outside the modal
• Support close with ESC, focus tooltip on show

v2.10.0 (06/14/2019)

• Add scrollIntoView options and polyfill
• Add TypeScript definitions
• Bugs fixed

06/10/2019

• v2.9.1

05/28/2019

• v2.9.0

05/04/2019

• v2.8.0