Interactive Tours

A tour can follow what happens in your app instead of the Next button. This page covers tours that advance on a click, wait for elements, skip optional steps and survive re-renders.

For tours where every step waits for a specific action and wrong actions get feedback, see Action-Driven Tours.

Advance on Click

advanceOn: "click" moves the tour on when the highlighted element is clicked, as if Next was pressed. The element’s own click handler still runs. Set it for the whole tour or per step.

import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver({
  advanceOn: "click",
  showProgress: true,
  steps: [
    { element: "#plan", popover: { title: "Pick a Plan" } },
    { element: "#billing", popover: { title: "Billing" } },
    { element: "#checkout", popover: { title: "Checkout" } },
  ],
});

driverObj.drive();

advanceOn takes any event, like "change" or "dblclick". To remove the Next button so the click is the only way forward, make the step an action step. advanceOnClick: true from earlier versions still works but is deprecated.

Wait for Elements

A click often leads to something that doesn’t exist yet, like a modal. Give the next step a waitForElement time in milliseconds: the tour stays on the current step, with its popover in a waiting state, until the element appears. Below, Next renders the element about a second later.

import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver({
  steps: [
    {
      element: "#open-modal",
      advanceOn: "click",
      popover: { title: "Open", instruction: "Click <b>Open</b>." },
    },
    {
      element: "#modal-confirm",
      waitForElement: 5000,
      popover: { title: "Confirm", description: "Now it's here." },
    },
  ],
});

driverObj.drive();

If the element never appears, the step shows without it, centered on the screen. To keep the user on the current step instead, set onElementMissing.

Optional Steps

Some elements only exist for some users. With skipMissingElement: true, a step whose element is not on the page is skipped, forwards and backwards. Run the tour below with and without the banner.

1,204 visits this week
const driverObj = driver({
  steps: [
    {
      element: "#stats",
      popover: {
        title: "Your numbers",
        description: "Updated every hour.",
      },
    },
    {
      element: "#trial-banner",
      skipMissingElement: true,
      popover: {
        title: "Trial banner",
        description: "Only trial accounts see this step.",
      },
    },
    {
      element: "#export",
      popover: {
        title: "Export",
        description: "Download the numbers as CSV.",
      },
    },
  ],
});

driverObj.drive();

Set it on the driver to apply it to every step. Steps without an element are never skipped. Combined with waitForElement, the step is skipped only after the wait runs out.

Elements That Re-render

Frameworks often replace an element instead of updating it. When the highlighted element is replaced, the step moves to the new element that matches its selector. There is nothing to configure. A step that got an element object instead of a selector or function has nothing to look up, so prefer selectors.

Integrations
Rendered once
const driverObj = driver({
  steps: [
    {
      element: "#sync-row",
      popover: {
        title: "Sync status",
        description: "Click <b>Sync now</b> a few times.",
      },
    },
  ],
});

driverObj.drive();

When the element is removed and nothing replaces it, onElementMissing decides what happens.

More Recipes