Tour

The tour methods allow you to start, navigate, and control tours programmatically. All methods are available on window.USETIFUL.tour after the usetiful:fullApiReady event has fired.

Tour IDs are numeric identifiers assigned in the Guides and Surveys dashboard when creating or editing a tour.

---

start(tourId, confirmation?, startStep?)

Starts a tour by its ID. By default, the tour begins at step 1 without a confirmation prompt.

When confirmation is true, the user sees a confirmation dialog before the tour begins. Use the startStep parameter to begin the tour at a specific step instead of the first one.

Parameter	Type	Required	Default
tourId	number	Yes	—
confirmation	boolean	No	false
startStep	number	No	1

window.USETIFUL.tour.start(tourId, confirmation?, startStep?)

Example

// Start tour 5 from the beginning
window.USETIFUL.tour.start(5);

// Start tour 5 with confirmation, beginning at step 2
window.USETIFUL.tour.start(5, true, 2);

---

nextStep()

Advances to the next step of the currently running tour. If the tour is already on its last step, calling this method completes the tour.

window.USETIFUL.tour.nextStep()

Example

window.USETIFUL.tour.nextStep();

---

preStep()

Returns to the previous step of the currently running tour. If the tour is on its first step, calling this method has no effect.

window.USETIFUL.tour.preStep()

Example

window.USETIFUL.tour.preStep();

---

jumpTo(step)

Jumps to a specific step in the currently running tour. Steps are 1-indexed, matching the step numbers defined in the Guides and Surveys dashboard.

Parameter	Type	Required
step	number	Yes

window.USETIFUL.tour.jumpTo(step)

Example

window.USETIFUL.tour.jumpTo(3);

---

close()

Closes the currently running tour. If no tour is active, this method has no effect.

window.USETIFUL.tour.close()

Example

window.USETIFUL.tour.close();

---

getState()

Returns the state of all tours as an array of tour objects. Each object includes the tour's ID, name, current state, availability, and — when the tour is in progress — the current step number.

Returns: an array of tour objects with the following properties:

Property	Type	Description
id	number	The tour ID
name	string	The tour name
state	string	One of 'never run', 'completed', 'inProgress', 'closed', or 'waiting'
isAvailable	boolean	Whether the tour is available to start
currentStep	number	The current step number (present only when state is 'inProgress')

window.USETIFUL.tour.getState()

Example

const tours = window.USETIFUL.tour.getState();

// Example return value:
// [
//   { id: 5, name: 'Onboarding', state: 'completed', isAvailable: true },
//   { id: 8, name: 'Feature Tour', state: 'inProgress', isAvailable: true, currentStep: 3 },
// ]

---

getToursByElement(selector)

Returns an array of tours that are triggered by or assigned to a specific DOM element. The selector parameter accepts any valid CSS selector string.

Use this method to determine which tours are associated with a particular UI element, for example to build custom navigation or to conditionally display tour-related controls.

Parameter	Type	Required
selector	string	Yes

window.USETIFUL.tour.getToursByElement(selector)

Example

const tours = window.USETIFUL.tour.getToursByElement('.my-button');