Fork me on GitHub

Bootstrap Tour

API Documentation

Global options

var tour = new Tour({
  name: "tour",
  steps: [],
  container: "body",
  smartPlacement: true,
  keyboard: true,
  storage: window.localStorage,
  debug: false,
  backdrop: false,
  backdropContainer: 'body',
  backdropPadding: 0,
  redirect: true,
  orphan: false,
  duration: false,
  delay: false,
  basePath: "",
  template: "<div class='popover tour'>
    <div class='arrow'></div>
    <h3 class='popover-title'></h3>
    <div class='popover-content'></div>
    <div class='popover-navigation'>
        <button class='btn btn-default' data-role='prev'>« Prev</button>
        <span data-role='separator'>|</span>
        <button class='btn btn-default' data-role='next'>Next »</button>
    </div>
    <button class='btn btn-default' data-role='end'>End tour</button>
  </div>",
  afterGetState: function (key, value) {},
  afterSetState: function (key, value) {},
  afterRemoveState: function (key, value) {},
  onStart: function (tour) {},
  onEnd: function (tour) {},
  onShow: function (tour) {},
  onShown: function (tour) {},
  onHide: function (tour) {},
  onHidden: function (tour) {},
  onNext: function (tour) {},
  onPrev: function (tour) {},
  onPause: function (tour, duration) {},
  onResume: function (tour, duration) {},
  onRedirectError: function (tour) {}
});
Name Type Description Default
name String This option is used to build the name of the storage item where the tour state is stored. The name should contain only alphanumerics, underscores and hyphens. You can initialize several tours with different names in the same page and application. 'tour'
steps Array A list of object representing the steps to be included in the tour. Jump to Step options for the single step API. []
container String Appends the step popover to a specific element.
See Usage section of Popover.
'body'
smartPlacement Boolean It dynamically reorients the popover by default by specifying auto for the placement, every time.
true
autoscroll Boolean Autoscrolls the window when the step popover is out of view. true
keyboard Boolean This option set the left and right arrow navigation. true
storage Object The storage system you want to use. Could be the objects window.localStorage, window.sessionStorage or your own object.
You can set this option as false to disable storage persistence (the tour starts from beginning every time the page is loaded).
Read more about DOM Storage interfaces.
window.localStorage
debug Boolean Set this option to true to have some useful informations printed in the console. false
backdrop Boolean Show a dark backdrop behind the popover and its element, highlighting the current step. false
backdropContainer NEW String (jQuery selector) HTML element on which the backdrop should be shown. 'body'
backdropPadding NEW Number|Object Add padding to the backdrop element that highlights the step element.
It can be a number or a object containing optional top, right, bottom and left numbers.
0
redirect Boolean|Function Set a custom function to execute as redirect function. The default redirect relies on the traditional document.location.href true
orphan Boolean|String|function Allow to show the step regardless whether its element is not set, is not present in the page or is hidden. The step is fixed positioned in the middle of the page. false
duration NEW Boolean|Number Set a expiration time for the steps. When the current step expires, the next step is automatically shown. See it as a sort of guided, automatized tour functionality. The value is specified in milliseconds false
delay NEW Boolean|Number Specifies a delay for the showing and hiding the tour steps. It can be:
  • a falsy - there is no delay
  • a number - used as a delay for both showing and hiding. In milliseconds
  • a object containing optional show and hide numbers - defines the delays for showing and hiding respectively
0
basePath String Specify a default base path prepended to the path option of every single step. Very useful if you need to reuse the same tour on different environments or sub-projects. ''
template String|Function String or function that returns a string of the HTML template for the popovers. If you pass a Function, two parameters are available: i is the position of step in the tour and step is the an object that contains all the other step options.
From version 0.5, the navigation template is included inside the template so you can easily rewrite it. However, Bootstrap Tour maps the previous, next and end logics to the elements which have the related data-role attribute. Therefore, you can also have multiple elements with the same data-role attribute.
"<div class='popover tour'>
  <div class='arrow'></div>
  <h3 class='popover-title'></h3>
  <div class='popover-content'></div>
  <div class='popover-navigation'>
    <button class='btn btn-default' data-role='prev'>« Prev</button>
    <span data-role='separator'>|</span>
    <button class='btn btn-default' data-role='next'>Next »</button>
    <button class='btn btn-default' data-role='end'>End tour</button>
  </div>
</div>"
afterGetState, afterSetState, afterRemoveState Function You may want to do something right after Bootstrap Tour read, write or remove the state. Just pass functions to these.
Your functions can have two parameters:
  • key Contains the name of the state being saved. It can be current_step (for the state where the latest step the visitor viewed is saved) or end (for the state which is saved when the user complete the tour). Note that Bootstrap Tour prepends the key with tour_ when saving the state.
  • value The value of the state been saved. Can be the index of the current step if the key is current_step, or yes if the key is end.

A simple example if to send a post request to your server each time there is a change:

var tour = new Tour({
  afterSetState: function (key, value) {
    $.post("/some/path", value);
  }
});
function (key, value) { }
onStart Function Function to execute when the tour starts. function (tour) { }
onEnd Function Function to execute when the tour ends. function (tour) { }
onShow Function Function to execute right before each step is shown. function (tour) { }
onShown Function Function to execute right after each step is shown. function (tour) { }
onHide Function Function to execute right before each step is hidden. function (tour) { }
onHidden Function Function to execute right after each step is hidden. function (tour) { }
onNext Function Function to execute when next step is called. function (tour) { }
onPrev Function Function to execute when prev step is called. function (tour) { }
onPause NEW Function Function to execute when pause is called. The second argument refers to the remaining duration. function (tour, duration) { }
onResume NEW Function Function to execute when resume is called. The second argument refers to the remaining duration. function (tour, duration) { }
onRedirectError NEW Function Function to execute when there is a redirection error. This happens when bootstrap tour cannot redirect to the path of the step function (tour) { }

Step Options

tour.addStep({
  path: "",
  host: "",
  element: "",
  placement: "right",
  smartPlacement: true,
  title: "",
  content: "",
  next: 0,
  prev: 0,
  animation: true,
  container: "body",
  backdrop: false,
  backdropContainer: 'body',
  backdropPadding: false,
  redirect: true,
  reflex: false,
  orphan: false,
  template: "",
  onShow: function (tour) {},
  onShown: function (tour) {},
  onHide: function (tour) {},
  onHidden: function (tour) {},
  onNext: function (tour) {},
  onPrev: function (tour) {},
  onPause: function (tour) {},
  onResume: function (tour) {},
  onRedirectError: function (tour) {}
});
Name Type Description Default
path String or RegExp Path to the page on which the step should be shown. This allows you to build tours that span several pages! ''
host NEW String or RegExp Host of the page on which the step should be shown. This allows you to build tours for several sub-domains ''
element String (jQuery selector) HTML element on which the step popover should be shown.
If orphan is false, this option is required.
''
placement String|Function How to position the popover. Possible choices: 'top', 'bottom', 'left', 'right', 'auto'. When "auto" is specified, it will dynamically reorient the popover. For example, if placement is "auto left", the popover will display to the left when possible, otherwise it will display right. 'right'
smartPlacement Boolean It dynamically reorients the popover by default by specifying auto for the placement. true
title String|Function Step title ''
content String|Function Step content ''
next Integer Index of the step to show after this one, starting from 0 for the first step of the tour. -1 to not show the link to next step. By default, the next step (in the order you added them) will be shown.
This option should be used in conjunction with prev.
0
prev Integer Index of the step to show before this one, starting from 0 for the first step of the tour. -1 to not show the link to previous step. By default, the previous step (in the order you added them) will be shown.
This option should be used in conjunction with next.
0
animation Boolean Apply a css fade transition to the tooltip. true
container String (jQuery selector) Attachment of popover. Pass an element to append the popover to. By default the popover is appended after the 'element' above. This option is particularly helpful for Internet Explorer. 'body'
backdrop Boolean Show a dark backdrop behind the popover and its element, highlighting the current step. false
backdropContainer NEW String (jQuery selector) HTML element on which the backdrop should be shown. 'body'
backdropPadding NEW Boolean|Object Add padding to the backdrop element that highlights the step element.
It can be a number or a object containing optional top, right, bottom and left numbers.
0
redirect Boolean|Function Set a custom function to execute as redirect function. The default redirect relies on the traditional document.location.href true
reflex UPDATED Boolean|String Enable the reflex mode: attach an handler on click on the step element to continue the tour.
In order to bind the handler to a custom event, you can pass a string with its name.
Also, the class tour-step-element-reflex is added to the element, as hook for your custom style (e.g: cursor: pointer).
false
orphan Boolean|String|Function Allow to show the step regardless whether its element is not set, is not present in the page or is hidden. The step is fixed positioned in the middle of the page.
You can use a string or function that returns a string of the HTML template for the orphan popovers
false
duration NEW Boolean|String Set a expiration time for the steps. When the step expires, the next step is automatically shown. See it as a sort of guided, automatized tour functionality. The value is specified in milliseconds false
template String|Function String or function that returns a string of the HTML template for the popovers. If you pass a Function, two parameters are available: i is the position of step in the tour and step is the object that contains all the other step options.
From version 0.5, the navigation template is included inside the template so you can easily rewrite it. However, Bootstrap Tour maps the previous, next and end logics to the elements which have the related data-role attribute. Therefore, you can also have multiple elements with the same data-role attribute.
"<div class='popover tour'>
  <div class='arrow'></div>
  <h3 class='popover-title'></h3>
  <div class='popover-content'></div>
  <div class='popover-navigation'>
    <button class='btn btn-default' data-role='prev'>« Prev</button>
    <span data-role='separator'>|</span>
    <button class='btn btn-default' data-role='next'>Next »</button>
    <button class='btn btn-default' data-role='end'>End tour</button>
  </div>
</div>"
onShow Function Function to execute right before the step is shown. It overrides the global onShow option. function (tour) { }
onShown Function Function to execute right after the step is shown. It overrides the global onShown option. function (tour) { }
onHide Function Function to execute right before the step is hidden. It overrides the global onHide option. function (tour) { }
onHidden Function Function to execute right after the step is hidden. It overrides the global onHidden option. function (tour) { }
onNext Function Function to execute when next step is called. It overrides the global onNext option. function (tour) { }
onPrev Function Function to execute when prev step is called. It overrides the global onPrev option. function (tour) { }
onPause NEW Function Function to execute when pause is called. The second argument refers to the remaining duration. It overrides the global the onPause option function (tour, duration) { }
onResume NEW Function Function to execute when resume is called. The second argument refers to the remaining duration. It overrides the global onResume option function (tour, duration) { }
onRedirectError NEW Function Function to execute when there is a redirection error. This happens when bootstrap tour cannot redirect to the path of the step. It overrides the global onRedirectError option function (tour) { }
Name Description
addSteps([]) Add multiple steps to the tour. Pass an array of objects.
addStep({}) Add single step to the tour. Pass an object.
init() Initialize the tour. You must do it before calling start.
start(true) Start the tour. Pass true to force the start.
restart() Restart the tour after it ended.
end() End the tour prematurely.
next() Skip to the next step.
prev() Go back to the previous step.
goTo(i) UPDATED Skip to a specific step. Pass i as the index of the step in the tour (0-based).
From version 0.7.0, the method has been renamed since some Javascript compilers are confused by the property name goto, which is a reserved word) .
pause() Pause the duration timer. It works only if tour or current step has duration.
resume() Resume the duration timer. It works only if tour or current step has duration.
ended() Verify if the tour ended. Returns boolean.
getStep(i) Get the step object. Pass i as the index of the step in the tour (0-based).
getCurrentStep() Get the index of the current step.
setCurrentStep(i) Override the current step. Pass i as the index of the step in the tour (0-based).
redraw() Triggers a redraw on the overlay element. Useful for Dynamically sized tour targets.

Bootstrap Tour can be used to create tours that span multiple pages. If you have URLs for each page that have unique paths, and the dependencies are loaded on each page, you can easily create a tour like so:

var tour = new Tour({
  steps: [
    {
      element: "#my-element",
      title: "Title of my step",
      content: "Content of my step"
    },
    {
      element: "#my-other-element",
      title: "Title of my step",
      content: "Content of my step",
      path: "/url/to/go/to/"
    }
  ]
});

It's that simple.

If you do not know the URL you wish to go to because it contains a different value per user or per instance, you can use a regular expression as the path attribute and set the redirect attribute to a function that performs the redirect.

For example:

var tour = new Tour({
  steps: [
    {
      element: "#my-element",
      title: "Title of my step",
      content: "Content of my step",
      redirect: function(){
        document.location.href = '/url/' + userId;
      };
    },
    {
      element: "#my-other-element",
      title: "Title of my step",
      content: "Content of my step",
      path: RegExp("\/url\/[^/]+", "i")
    }
  ]
});

Finally, if you are only using GET parameters to define different pages, and wish to redirect using those parameters, you may run into the problem that Bootstrap Tour will consider the path of the two steps to be identical. For example, you cannot use the path parameter to go from your homepage at / to a search results page at /?q=foo, because from Bootstrap Tour's perspective, those are the same location (/).

To work around this limitation, you can set the onNext attribute a function that returns a promise.

For example:

var tour = new Tour({
  steps: [
    {
      element: "#my-element",
      title: "Title of my step",
      content: "Content of my step",
      onNext: function(){
        document.location.href = '/?q=foo';
        return (new jQuery.Deferred()).promise();
      };
    },
    {
      element: "#my-other-element",
      title: "Title of my step",
      content: "Content of my step",
    }
  ]
});

Doing this will prevent the next step from popping up while the redirect is being completed in the onNext function.