Responsive Guided App Tour In JavaScript – shepherd

Preview:

Description:

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

Full responsive, user-friendly and mobile compatible.

The library requires Tether.js which is a client-side library to make absolutely positioned elements attach to elements in the page efficiently.

How to use it:

Import the necessary Tether.js and shepherd.js into the document.

<script src="tether.js"></script>
<script src="shepherd.js"></script>

Create a new tour.

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

Add steps to the tour.

myTour.addStep('step-1', {
  title: 'Step 1',
  text: 'This is Step 1',
  attachTo: '.where-to-attach',
  advanceOn: '.advance-on'
});

Start the tour.

myTour.start();

All default tour options.

let myTour = new Shepherd.Tour({

    // an array of Steps
    steps: [],

    //  Default options for Steps
    defaults: {}
    
})

All default step options.

myTour.addStep('stepName', {

  // 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: '',

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

  // extra classes
  classes: '',

  // an array of buttons to add to the step. 
  buttons: [{
    text: '',
    classes: '',
    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: '',

  // shows cancel link
  showCancelLink: true or false

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

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

});

Tour’s API.

// Methods
myTour.addStep(id, options)
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:

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