Skip to main content

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​

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.

Parameters
  • tourId number required

    Default value: —

    The tour ID.

  • confirmation boolean optional

    Default value: false

    Whether to show a confirmation dialog before the tour begins.

  • startStep number optional

    Default value: 1

    The step number to begin the tour at.

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​

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.

Parameters
  • step number required

    The step number to jump to.

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:

Properties
  • id number required

    The tour ID.

  • name string required

    The tour name.

  • state string required

    One of 'never run', 'completed', 'inProgress', 'closed', or 'waiting'.

  • isAvailable boolean required

    Whether the tour is available to start.

  • currentStep number optional

    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​

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.

Parameters
  • selector string required

    A CSS selector string identifying the target element.

window.USETIFUL.tour.getToursByElement(selector)

Example​

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