How to Build a User Tour With Shepherd in JavaScript

What You'll Be Creating

Regardless of how simple we try to make our web applications, it's often helpful to guide new users through their first experience. Visual tours are likely the easiest way.

If you've followed my Envato Tuts+ Building Your Startup With PHP series, you're familiar with Meeting Planner. After watching users scheduling their first meeting, I decided it would be best to build some kind of guide.

At first, I considered building it myself, but then I found an open-source option, Shepherd.

In today's tutorial, I'll introduce you to building a visual user tour with Shepherd. Using Shepherd is relatively straightforward, and I'll review some of my own code that I used to streamline the authoring process.

Shepherd is an open-source offering from HubSpot, an inbound marketing service. Kudos to them for offering a robust library with good documentation.

How Shepherd Works

Let's walk through a simple scenario for Shepherd.

Integrating a basic tour to your application with Shepherd is straightforward. First, you choose a theme file and integrate their JavaScript like this:

1	<link rel="stylesheet" href="shepherd-theme-arrows.css" />
2	<script src="tether.min.js"></script>
3	<script src="shepherd.min.js"></script>

You can download the files from the Shepherd GitHub page. I'm using the shepherd-theme-arrows.css above, but you can choose from any of the defaults below and customize them:

Next, you create a tour object:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

The defaults can be defined for all steps when you create the tour using the defaultStepOptions key. The classes refer to the theme definitions you used, e.g. shepherd-theme-arrows, and scrollTo helpfully ensures all steps appear in the visible viewport with the help of the scrollIntoView() method.

Then, you add individual steps to the tour:

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

The text is what appears in the body of the visual tour. The text can either be a regular HTML string or an HTMLElement object. You can also provide a callback function here that will be executed when the step is built. However, it must return either an HTML string or an HTMLElement object.

The attachTo key points to a CSS selector for the item to which you want to attach this step. It expects an object as its value.

The buttons key allows you to define one or more buttons and their actions, eg. Next. This key accepts an array of button objects as its value. The button objects will have key-value pairs that control the buttons' behavior and appearance.

And finally, you start the tour:

1	tour.start();

Shepherd builds on Tether, another HubSpot open-source offering, which helps position elements to other elements on a page. Tether makes sure your steps never overflow the screen or get cropped.

Integrating Tether Into Your Own Application

As I began experimenting with Shepherd, I discovered quickly that authoring a guide with many steps could get fairly lengthy. This is something I addressed in my own implementation.

I didn't want to author the tour with a lengthy bundle of JavaScript code which would need to be maintained over time. Instead, I chose to create an array and programmatically customize the buttons based on whether users were at the beginning or the end of the tour.

For example, I create a steps[] array and defined the tour by populating the array:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

const steps = [];

steps.push({
  attachTo: {
    element: '.nav-tabs',
    on: 'top'
  },
  title: 'Welcome',
  text: `Allow me to show you how to plan a ${title}. <p>If you prefer, you can <a href="javascript::return false;" onclick="turnOffGuide();">turn off this guide</a>.<br /><br />`
});
steps.push({
  attachTo: {
    element: '#headingWho',
    on: 'top'
  },
  title: 'Who would you like to invite?',
  text: `You can add one person or a group of people to your ${title}. <p>Click the person button to add participants.</p>`
});
steps.push({
  attachTo: {
    element: '#invitation-url',
    on: 'bottom'
  },
  title: 'Inviting by email',
  text: 'Alternately, you can email the meeting link to your participant(s)'
});
steps.push({
  attachTo: {
    element: '#headingWhat',
    on: 'bottom'
  },
  title: 'What is your meeting about?',
  text: `You can customize the subject of your ${title}. We'll use it for the invitation and reminder emails.<p>Click the pencil button to edit the subject.</p>`
});
if ($('#headingActivity').length > 0) {
  steps.push({
    attachTo: {
      element: '#headingActivity',
      on: 'top'
    },
    title: 'What do you want to do?',
    text: 'You can suggest one or more activity ideas. With multiple ideas, your participants can help you select their favorite. <p>Click the plus button to suggest activities.</p>'
  });
}
steps.push({
  attachTo: {
    element: '#headingWhen',
    on: 'top'
  },
  title: 'When do you want to meet?',
  text: `Suggest one or more dates and times for your ${title}. With more than one, your participants can help you choose. <p>Click the + button to add them.</p>`
});
steps.push({
  attachTo: {
    element: '#headingWhere',
    on: 'top'
  },
  title: 'Where do you want to meet?',
  text: `Suggest one or more places for your ${title}. With multiple places, your participants can help you choose. <p>We use Google Places to simplify adding them. Click the + button to begin.</p>`
});
steps.push({
  attachTo: {
    element: '.virtualThing',
    on: 'top'
  },
  title: 'Is this a virtual meeting?',
  text: `Switch between <em>in person</em> and <em>virtual</em> ${title}s such as phone calls or online conferences.`
});
steps.push({
  attachTo: {
    element: '#actionSend',
    on: 'top'
  },
  title: 'Sending invitations',
  text: `Scheduling is collaborative. After you add times and places, you can <strong>Invite</strong> participants to select their favorites. <em>A place isn't necessary for virtual ${title}s.</em>`
});
steps.push({
  attachTo: {
    element: '#actionFinalize',
    on: 'right'
  },
  title: 'Finalizing the plan',
  text: `Once you choose a time and place, you can <strong>Complete</strong> the plan. We'll email the invitations and setup reminders.`


});
steps.push({
  attachTo: {
    element: '#tourDiscussion',
    on: 'left'
  },
  title: 'Share messages with participants',
  text: 'You can write back and forth with participants on the <strong>Messages</strong> tab. <p>Messages are delivered via email.</p>'
});
steps.push({
  attachTo: {
    element: '.container',
    on: 'top'
  },
  title: 'Ask a question',
  text: `Need help? <a href="${$('#url_prefix').val()}/ticket/create">Ask a question</a> and we'll respond as quickly as we can. <p>If you prefer, you can <a href="${$('#url_prefix').val()}/user-setting?tab=guide">turn off the guide</a> in settings.</p>`
});

Each object element that I added to the array includes three crucial pieces of information:

the CSS visual element this step points to and where it should be attached to that element. e.g. {element: '.nav-tabs', on:'top'}
text for the header in the title key, e.g. 'When do you want to meet?'
text for the instruction in the text key

Maintaining this array was much simpler for me than defining buttons for every single step of the tutorial. However, this meant that I needed to programmatically define buttons as I loaded the steps into the tour.

I wrote this code to add and respond to buttons for the tour properly. With each step, it creates a buttons array, which I would otherwise have to define manually:

for (let i = 0; i < steps.length; i++) {
    
    let buttons=[];
    
    // no back button at the start 
    if (i>0) {
        buttons.push({
          text: 'Back',
          classes: 'shepherd-button-secondary',
          action: function() {
            return tour.back();
          }
        });
    }
    
    // no next button on last step 
    if (i!=(steps.length-1)) {
        buttons.push({
          text: 'Next',
          classes: 'shepherd-button-primary',
          action: function() {
            return tour.next();
          }
        });
    } else {
        buttons.push({
          text: 'Close',
          classes: 'shepherd-button-primary',
          action: function() {
            return tour.hide();
          }
        });
    }

For example, the first step has no Back button, and the last step has no Next button. But the last step does have a Close button.

Then, each step from my array and each button array is added to the tour.

    tour.addStep(`step_${i}`, {
        text: steps[i].text,
        title: steps[i].title,
        attachTo: steps[i].attachTo,
        classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
        buttons: buttons,
    });
}

Using this approach, I didn't have to repeatedly redefine the same buttons for every step of my tutorial. It also offers some programmatic ability to customize the tour dynamically for the future.

Using Yii, my chosen PHP programming framework, I added necessary include files to my asset file. This gets loaded on particular pages where the tour is needed. In my case, the meeting scheduling page:

<?php
namespace frontend\assets;
use yii\web\AssetBundle;
class MeetingAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
      ...
      'css/shepherd-theme-arrows.css',      
    ];
    public $js = [
      'js/meeting.js',
      ...
      'js/tether.min.js',
      'js/shepherd.min.js',
      'js/meeting_tour.js',
    ];
    ...

You'll see above the CSS for the Shepherd theme and the JavaScript for Tether, Shepherd, and my tour definition file, meeting_tour.js.

I also added CSS to control the overall width of my tour popup to 40% of the viewport:

1	.shepherd-element.shepherd-theme-arrows {
2	max-width: 40%;
3	}

You can watch the example tour video above or on Vimeo. If you'd like to try it yourself, sign up at Meeting Planner and you'll be immediately taken to the scheduling tour.

Other Things to Consider

Turning Off the Visual Tour

I created a user setting for people to quickly turn off the tour. Rather than include a distracting off button on every step, I added a link to turn off the guide on the first and last steps of the tour:

Turning it off happens interactively via AJAX and displays a helpful link to the settings page below. This helps new users easily find how to turn the tour back on:

Shepherd's Advanced Capabilities

I've just been showing you the basics of Shepherd and how to integrate it quickly into your web application. So far, it's worked well for me aside from the occasional problems with arrows. However, Shepherd offers a lot more than I've reviewed, specifically around event processing and management. This allows you to adapt your tour to your application and the user's current state in a more customized way. They have very good documentation too.

For example, if a user jumps to some area of your web page, you can have the event automatically trigger a jump to another step of the tour. I might dive into this in a future tutorial.

In Closing

I hope you've enjoyed learning about Shepherd. It certainly is a visually polished, developer-friendly visual tour that you can quickly integrate into any application.

Shepherd on GitHub
Meeting Planner (create your first meeting to see the visual tour)

This post has been updated with contributions from Monty Shokeen. Monty is a full-stack developer who also loves to write tutorials and learn about new JavaScript libraries.