Usage
Rollup/Webpack Based Builds
The latest versions of Rollup and Webpack support ES6 imports. Shepherd ships as an ES module which should allow you to import using standard ES import syntax.
i.e.
First create a new Tour
instance for your tour:
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:
Finally, to start the tour, just call start
on your Tour
instance:
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.
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
Shepherd.on(eventName, handler, [context])
: Bind an eventShepherd.off(eventName, [handler])
: Unbind an eventShepherd.once(eventName, handler, [context])
: Bind just the next instance of an event
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:
complete
cancel
hide
show
start
active
inactive
For multiple events, you can use something like:
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:
Shepherd.activeTour
Tour Instances
Creation
You create a Tour
object for each tour you’d like to create.
Tour’s constructor accepts a hash of options:
Tour Options
classPrefix
: The prefix to add to theshepherd-enabled
andshepherd-target
class names as well as thedata-shepherd-step-id
.confirmCancel
:- If true, will issue a
window.confirm
before cancelling - If it is a function(support Async Function), it will be called and wait for the return value, and will only be cancelled if the value returned is true
- If true, will issue a
confirmCancelMessage
: The message to display in the confirm dialogdefaultStepOptions
: Default options for Steps created throughaddStep
exitOnEsc
: Exiting the tour with the escape key will be enabled unless this is explicitly set tofalse
.keyboardNavigation
: Navigating the tour via left and right arrow keys will be enabled unless this is explicitly set tofalse
.stepsContainer
An optional container element for the steps. If not set, the steps will be appended todocument.body
.modalContainer
An optional container element for the modal. If not set, the modal will be appended todocument.body
.steps
: An array of step options objects or Step instances to initialize the tour with.tourName
: An optional “name” for the tour. This will be appended to the the tour’s dynamically generatedid
property.useModalOverlay
: 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.
Tour Methods
addStep(options)
: Creates a new Step object with options, and returns theStep
instance it created. If the options hash doesn’t include anid
, one will be generated. You can also pass an existingStep
instance rather thanoptions
, but note that Shepherd does not support a Step being attached to multiple Tours.addSteps([Steps])
: Add multiple steps to the tourgetById(id)
: Return a step with a specific idisActive()
: Check if the tour is activenext()
: Advance to the next step, in the order they were addedback()
: Show the previous step, in the order they were addedcancel()
: Trigger cancel on the current step, hiding it without advancingcomplete()
: Calls _done() triggering thecomplete
eventhide()
: Hide the current stepshow([id])
: Show the step specified by id (if it’s a string), or index (if it’s a number) provided. Defaults to the first step.start()
: Show the first step and begin the tourgetCurrentStep()
: Returns the currently shown stepremoveStep(id)
: Removes the step from the touron(eventName, handler, [context])
: Bind an eventoff(eventName, [handler])
: Unbind an eventonce(eventName, handler, [context])
: Bind just the next instance of an event
Tour Events
complete
: Triggered when the last step is advancedcancel
hide
show
: Triggered with a hash of thestep
and theprevious
stepstart
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
text
: The text in the body of the step. It can be one of three types:- HTML string
HTMLElement
objectFunction
to be executed when the step is built. It must return one the two options above.
title
: The step’s title. It becomes anh3
at the top of the step.attachTo
: The element the step should be attached to on the page. An object with propertieselement
andon
.element
: An element selector string, a DOM element, or a function (returning a selector, a DOM element,null
orundefined
).on
: The optional direction to place the Floating UI tooltip relative to the element.- Possible string values: ‘top’, ‘top-start’, ‘top-end’, ‘bottom’, ‘bottom-start’, ‘bottom-end’, ‘right’, ‘right-start’, ‘right-end’, ‘left’, ‘left-start’, ‘left-end’
If you don’t specify an attachTo
the element will appear in the middle of the screen. The same will happen if your
attachTo.element
callback returns null
, undefined
, or a selector that does not exist in the DOM.
If you omit the on
portion of attachTo
, the element will still be highlighted, but the tooltip will appear
in the middle of the screen, without an arrow pointing to the target.
If the element to highlight does not yet exist while instantiating tour steps, you may use lazy evaluation by supplying a function to attachTo.element
. The function will be called in the before-show
phase.
beforeShowPromise
: A function that returns a promise. When the promise resolves, the rest of theshow
code for the step will execute. For example:canClickTarget
A boolean, that when set to false, will setpointer-events: none
on the targetcancelIcon
Options for the cancel iconenabled
Should a cancel “✕” be shown in the header of the step?label
The label to add foraria-label
classes
: A string of extra classes to add to the step’s content element.buttons
: An array of buttons to add to the step. These will be rendered in a footer below the main body text. Each button in the array is an object of the format:label
: The label to add foraria-label
. It can also be a function that returns a string (useful with i18n solutions).disabled
: A boolean that controls thedisabled
attribute. It can also be a function that returns a boolean.classes
: Extra classes to apply to the<a>
secondary
: A boolean, that when true, adds ashepherd-button-secondary
class to the buttontext
: The HTML text of the button. It can also be a function that returns a string (useful with i18n solutions).action
: A function executed when the button is clicked on. It is automatically bound to thetour
the step is associated with, so things likethis.next
will work inside the action. You can use action to skip steps or navigate to specific steps, with something like:
advanceOn
: An action on the page which should advance shepherd to the next step. It should be an object with a stringselector
and anevent
name. For example:{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 callingmyTour.next()
.highlightClass
: An extra class to apply to theattachTo
element when it is highlighted (that is, when its step is active). You can then target that selector in your CSS.id
: The string to use as theid
for the step. If an id is not passed one will be generated.modalOverlayOpeningPadding
: An amount of padding to add around the modal overlay openingmodalOverlayOpeningRadius
: An amount of border radius to add around the modal overlay opening. It can be either a number or an object with properties{ topLeft, bottomLeft, bottomRight, topRight }
floatingUIOptions
: Extra options to pass to Floating UIshowOn
: A function that, when it returns true, will show the step. If it returns false, the step will be skipped.scrollTo
: Should the element be scrolled to when this step is shown? If true, uses the defaultscrollIntoView
, if an object, passes that object as the params toscrollIntoView
i.e.{behavior: 'smooth', block: 'center'}
scrollToHandler
: A function that lets you override the defaultscrollTo
behavior and define a custom action to do the scrolling, and possibly other logic.when
: You can define show, hide, etc events inside when. For example:
Step Methods
show()
: Show this stephide()
: Hide this stepcancel()
: Hide this step and trigger thecancel
eventcomplete()
: Hide this step and trigger thecomplete
eventscrollTo()
: Scroll to this step’s elementisOpen()
: Returns true if the step is currently showndestroy()
: Remove the elementon(eventName, handler, [context])
: Bind an eventoff(eventName, [handler])
: Unbind an eventonce(eventName, handler, [context])
: Bind just the next instance of an event
Step Events
before-show
show
before-hide
hide
complete
cancel
destroy
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:
🔼 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 the arrow
option to true
on each “Step.options` — but you can disable the arrow manually by setting it to false:
Furthermore, while Shepherd provides some basic arrow styling, you can style it as you wish by targeting the .shepherd-arrow
element.