API Reference

driver() returns an object with the methods below. The options it takes are in Configuration.

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

const driverObj = driver({
  steps: [
    { element: "#search", popover: { title: "Search" } },
    { element: "#export", popover: { title: "Export" } },
  ],
});

Starting and Stopping

driverObj.drive(); // Start the tour at the first step
driverObj.drive(2); // Start at the third step

// Show one step on its own, without a tour
driverObj.highlight({
  element: "#search",
  popover: { title: "Search", description: "Find anything." },
});

driverObj.destroy(); // End the tour or highlight
driverObj.isActive(); // true while a tour or highlight is showing

destroy() doesn’t run onDestroyStarted, so you can call it from that hook. The other destroy hooks get the reason "api", or the reason of the user action when you call it from a hook.

driverObj.moveNext(); // Go to the next step. Ends the tour on the last one
driverObj.movePrevious(); // Go to the previous step
driverObj.moveTo(3); // Go to the step with this index
driverObj.advance(); // Complete the current step

advance() completes the step the way advanceOn does: it waits for advanceDelay, then runs onNextClick or moves on. Use it when your app decides the step is done, like after a save. moveNext() moves right away and doesn’t run onNextClick.

{
  element: "#save",
  advanceDelay: 600,
  onHighlighted: (element, step, { signal, driver }) => {
    window.addEventListener("profile-saved", () => driver.advance(), {
      signal,
    });
  },
  popover: {
    title: "Save your profile",
    instruction: "Click <b>Save</b>.",
  },
}

movePrevious() on the first step and moveTo() with an index that doesn’t exist end the tour. moveTo() also starts the tour when it isn’t running, like drive(). moveNext() and movePrevious() do nothing then.

The Current Step

driverObj.getActiveIndex(); // Active step index, undefined in highlight()
driverObj.getActiveStep(); // The active step
driverObj.getActiveElement(); // The highlighted element

driverObj.getPreviousStep(); // The step that was active before this one
driverObj.getPreviousElement(); // And its element
driverObj.getNextStep(); // The step moveNext() would show

driverObj.isFirstStep(); // No step to go back to
driverObj.isLastStep(); // No step to go on to
driverObj.hasNextStep();
driverObj.hasPreviousStep();

These account for steps that skipMissingElement would skip. isFirstStep() and isLastStep() return false when no tour is running.

Changing the Popover

// Change the visible popover. Changes merge, and last until the step
// is left.
driverObj.updatePopover({ description: "Almost there." });
driverObj.updatePopover({
  nextBtnText: "Continue",
  disableButtons: ["previous"],
});

// Restore the step's own popover
driverObj.updatePopover();

updatePopover() takes title, description, instruction, showButtons, disableButtons, showProgress, progressText, nextBtnText, prevBtnText, closeBtnLabel and popoverClass. Changed text is announced to screen readers. It can change the text of an action step, but not turn a step into one.

// Shake the popover to draw attention to it
driverObj.nudge();

// Shake it and show a line of feedback under the instruction.
// The line goes away with the next nudge() or step.
driverObj.nudge("Not that one. Click <b>Inbox</b>.");

// Shake it and change the popover like updatePopover() does
driverObj.nudge({ description: "Not quite. Choose Editor." });
// Redraw the highlight and popover after a layout change.
// Resizes, scrolling and size changes of the element are followed already.
driverObj.refresh();

Configuration

driverObj.getConfig(); // The current configuration
driverObj.getState(); // The current state, see Configuration
driverObj.getState("activeIndex"); // One key of it

// Replace the steps
driverObj.setSteps([
  { element: "#billing", popover: { title: "Billing" } },
]);

// Replace the configuration
driverObj.setConfig({ ...driverObj.getConfig(), showProgress: true });

setConfig() replaces the whole configuration, including steps. Spread getConfig() to keep what you had. After setSteps() on a running tour, call drive() to show the new steps.

Types

import type {
  Config,
  DriveStep,
  Popover,
  Driver,
  State,
  PopoverDOM,
  PopoverPatch,
  DriverHook,
  HookOpts,
  DestroyReason,
  AdvanceOn,
  AdvanceOnEvent,
  AllowedElements,
  InteractionHook,
  ElementMissing,
  ElementMissingHook,
  Side,
  Alignment,
  AllowedButtons,
} from "driver.js";

Hints

hints() returns its own object. Options are in Hints Configuration, examples in the Hints guide.

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

const productHints = hints({
  hints: [
    { element: "#export", id: "export", popover: { title: "Export" } },
  ],
});

// Show the beacons. Call again to pick up elements that appeared since
productHints.show();
productHints.hide(); // Remove the beacons
productHints.isVisible();

// By id, or by index when the hint has no id
productHints.open("export"); // Open a hint's popover
productHints.close(); // Close the open popover, keeping its beacon
productHints.dismiss("export"); // Remove a hint's beacon and run onDismiss
productHints.restore("export"); // Bring a dismissed hint back
productHints.restoreAll();

productHints.getHints(); // The configured hints
productHints.getActive(); // The hint whose popover is open, if any
productHints.setHints([]); // Replace the hints. Dismissals are forgotten

productHints.refresh(); // Reposition after a layout change

Checklists

checklist() returns its own object. Options are in Checklist Configuration, examples in the Checklists guide.

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

const onboarding = checklist({
  id: "onboarding",
  items: [
    {
      id: "tour",
      title: "Take the tour",
      tour: [{ element: "#search", popover: { title: "Search" } }],
    },
    { id: "github", title: "Connect GitHub" },
  ],
});

onboarding.show(); // Add the widget to the page
onboarding.hide(); // Remove it
onboarding.isVisible();

onboarding.open(); // Open the panel
onboarding.close(); // Close the panel, keeping the launcher
onboarding.toggle();
onboarding.isOpen();

onboarding.start("tour"); // Run an item's tour, link or action
onboarding.complete("github"); // Tick an item
onboarding.uncomplete("github"); // Untick it
onboarding.reset(); // Untick every item
onboarding.refresh(); // Check every item's completeWhen again

onboarding.getProgress(); // { completed: ["github"], done: 1, total: 2 }
onboarding.getItems(); // The configured items