Shepherd

Guide your users through a tour of your app.

Dependencies

Tippy.js

Install

npm

npm install shepherd.js --save

yarn

yarn add shepherd.js

Install with Eager

Note: Eager is now Cloudflare Apps

We will eventually make this work again, but it probably currently does not.

Usage

First create a new Tour instance for your tour:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shadow-md bg-purple-dark',
    scrollTo: true
  }
});

The defaultStepOptions option allows you to specify any options which should be applied to all this tour’s steps by default.

Next, add your steps:

tour.addStep('example-step', {
  text: 'This step is attached to the bottom of the <code>.example-css-selector</code> element.',
  attachTo: '.example-css-selector bottom',
  classes: 'example-step-extra-class',
  buttons: [
    {
      text: 'Next',
      action: tour.next
    }
  ]
});

Finally, to start the tour, just call start on your Tour instance:

tour.start();

If you need to remove a step from your tour, call removeStep on your Tour instance. If the step currently being displayed is the one you’re removing, and there are steps left in the tour, then the first one will be shown, otherwise, the tour will be cancelled.

tour.removeStep('example-step');

API

Global Shepherd Object

Shepherd exposes a single object onto the window, Shepherd.

That global object fires several events to let you link up actions with events occurring in any tour:

Methods
Events

The global Shepherd fires the following events whenever a Tour instance fires them. It adds to the object passed to the event handlers a tour key pointing to the instance which fired the event:

Current Tour

The global Shepherd includes a property which is always set to the currently active tour, or null if there is no active tour:

Tour Instances

Creation

You create a Tour object for each tour you’d like to create.

Tour’s constructor accepts a hash of options:

const myTour = new Shepherd.Tour(options);
Tour Options
Tour Methods
Tour Events

Steps are instances of the Step object. They are generally created by the Tour::addStep method, which returns the Step instance it created.

Steps

Step Options
Step Methods
Step Events

Please note that complete and cancel are only ever triggered if you call the associated methods in your code.

Advancing on Actions

You can use the advanceOn option, or the Next button, to advance steps. If you would like however to have a step advance on a complex user action, you can do the following:

const myStep = myTour.addStep('my-step', options);

yourApp.on('some-event', () => {
  if (myStep.isOpen()){
    Shepherd.activeTour.next();
  }
});

It’s strongly recommended that you use some sort of event mediator to connect your app’s actions with Shepherd, to prevent having to sprinkle Shepherd code throughout your codebase, and to keep things loosely coupled. You can create a basic mediator if need be using the Evented object which is provided with Shepherd:

const mediator = new Shepherd.Evented();

You can then trigger events in one part of your app:

mediator.trigger('user-create');

And listen for them in other areas:

mediator.on('user-create', () => {});

Rendering Tours in Specific Locations

By default, tour steps will append their elements to the body element of the DOM. This is perfect for most use cases, but not always. If you need to have steps appended elsewhere you can take advantage of Tippy’s appendTo option by defining it on the tippyOptions hash inside of each Step’s options hash.

Browser Support

IE9+ and all modern browsers

Theming and Styling

We deliver some predefined themes (e.g., shepherd-theme-default or shepherd-theme-square). You are welcome to use one of them by embedding its stylesheet into your app.

<head>
  <link rel="stylesheet" href="shepherd-theme-default.css">
</head>

If you’d like to extend a theme within your own CSS, you can pass custom class names to the tour instance — or, as part of the options for each step — and use them as hooks for your own styling rules.

let tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-custom'
  }
});

Leveraging Sass Variables

We use SASS as pre-processor for CSS. This allows us to extend the CSS language with various syntax techniques — including variables and color functions that can be used to control theming.

These values and variables can be found in _variables.scss, and the ones that can be adjusted for theming are listed below.

🎨 Color Settings

Variable Purpose Default
$shepherd-theme-primary Primary or brand color. The primary button gets this color. #3288e6
$shepherd-theme-secondary Secondary color. If it is not set explicitly, it is calculated using the primary color. desaturate(lighten($shepherd-theme-primary, 40), 70)
$shepherd-text-background Background color of the text area. #ffffff
$shepherd-header-background Background color of the header element. If it is not set explicitly, it is calculated using the text background color. darken($shepherd-text-background, 10)

⚙️ Options

Variable Purpose Default
$shepherd-element-width Width of the step element 400px
$shepherd-element-border-radius Set radius of rounded corners. 0 means (sharp) pointed corners. 5px
$shepherd-element-max-height Maximum height of the element 100%
$shepherd-element-max-width Maximum width of the element 100%
$shepherd-element-z-index Move the element forward or backward 9999
$shepherd-text-line-height Determine the line height of the body text 1.3em
$shepherd-button-border-radius Decide whether the buttons should have rounded or pointed corners. 0 means (sharp) pointed corners. 3px
$use-drop-shadow The element casts a shadow true

The example below is intended to illustrate the individual customizations. Please make sure that the values are set before the import of the base-theme.

$shepherd-theme-primary: #9b59b6 !default;
$shepherd-theme-secondary: desaturate(lighten($shepherd-theme-primary, 30), 70) !default;
$shepherd-header-background: #eeeeee !default;
$shepherd-element-border-radius: 0 !default;
$shepherd-button-border-radius: 0 !default;
$use-drop-shadow: true !default;

@import 'base';

As a result you get a squared theme with a purple primary button. The individual steps cast a shadow on the underlying elements. The header is colored in a light gray tone.

🔼 Displaying Arrows

By default, Shepherd will generate and position an “arrow” element that points to the target of a step. This is done by setting Tippy’s arrow option to true on each ``Step.options.tippyOptions` — but you can disable the arrow manually by setting it to false:

myTour.addStep('Step 1', {
  tippyOptions: {
    arrow: false
  }
});

Furthermore, while each of Shepherd’s themes provides some basic arrow styling, you can style it as you wish by targeting the markup that’s genereated by Tippy.

Projects Using Shepherd

Here we showcase some of the awesome libraries built using Shepherd.

ember-shepherd

Ember addon for the site tour library Shepherd

SimplePlanner

SimplePlanner uses Shepherd to help new users get familiar with its collaborative scheduling approach. You do need to sign up via OAuth or email to see the scheduling tour. Check out the Envato Tuts+ Startup Series on its codebase which describes how Simple Planner was built.

Your Project Here

If you have a cool open-source library built on Shepherd, PR this doc.