Responsive Guided App Tour In JavaScript – shepherd

Category: Javascript , Recommended | September 3, 2023
Author:shipshapecode
Views Total:285 views
Official Page:Go to website
Last Update:September 3, 2023
License:MIT

Preview:

Responsive Guided App Tour In JavaScript – shepherd

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:

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/shepherd.js@latest/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:

v11.2.0 (09/03/2023)

  • Prevent ESC, KEY_RIGHT, KEY_LEFT propagation when keyboardNav is enabled

v11.1.1 (04/04/2023)

  • Bugfix

v11.1.0 (04/03/2023)

  • add funtion support for confirmCancel
  • prevent to show spurious warnings in dev panel consol

v11.0.1 (12/13/2022)

  • Bugfix

v11.0.0 (11/22/2022)

  • Replace popperJS with Floating UI
  • Exporting StepOptionsButton type to be able to add tour steps buttons dynamically with type checking
  • feat: add ability to specify corner radius
  • Bug Fix

v10.0.1 (08/01/2022)

  • Bug Fix

v10.0.0 (06/06/2022)

  • Implement lazy evaluation of attachTo.element
  • Fix chrome opacity bug

v9.1.1 (05/25/2022)

  • Fixed showOn incorrectly skipping an index

v9.1.0 (04/09/2022)

  • Add dynamic text and label properties for buttons

v9.0.0 (01/11/2022)

  • Drop node 10 support
  • Fix type signature for Evented.off()
  • Bug Fix

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

You Might Be Interested In:


Leave a Reply