Shepherd is a JavaScript library that provides a simple interface for creating guided user journeys in web applications. It's framework-agnostic, easy to use, and works great on desktop and mobile applications alike.
Guided user journeys or product tours are a popular way to onboard new users and help existing users to discover new functionality in applications.
To start a new guided tour using Shaperd, install the library using npm/yarn or grab it directly from the CDN provided in the installation guide and then initialize the tour and add the desired steps to the tour following the example below.
// only needed when installing via npm/yarn
import Shepherd from 'shepherd.js';
const exampleTour = new Shepherd.Tour({
useModalOverlay: true,
defaultStepOptions: {
scrollTo: true
}
});
In this example, we add two custom properties during initialization.
useModalOverlay creates a backdrop behind the tour modal and the target element, which makes it much more readable.
scrollTo tells Shepherd to scroll the target element into view when the step is shown.
tour.addSteps([{
id: 'first-step',
text: 'This is the first step of the tour',
attachTo: {
element: '.example-css-selector',
on: 'bottom'
}
}]);
Once the tour is initialized, the developer adds the individual steps through the addSteps method, passing in an array of steps.
Finally, tour.start() will kick the tour off. Developers should consider adding a setTimeout to avoid triggering the tour immediately. Developers should also track which guided tours have been displayed to the user in order to avoid displaying them again on every visit.
The defaults used by Shepherd do not take advantage of the library capabilities, and developers are advised to read the full tutorial and API documentation in order to make the most out of the library.
It's worth noting that under the hood, Sheperd uses Floating UI, formally called Popper.js, a tooltip and popover positioning engine that ensures the dialog windows always remain visible and properly positioned.
While developers can use Shepherd out of the box with any framework, there are many user-maintained libraries to ease the integration (such as React Shepherd). Developers can find links to popular integration in the Shepherd Github repository.
Shepherd source code can be found at the official repository on Github and is provided under the MIT license.
Developers are encouraged to participate in developing and maintaining Shepherd by following the contributing guide.
