Headless Tours

driver.js/headless runs a tour without any UI. It finds each step’s element, waits for it, listens for advanceOn and calls your hooks. It draws no overlay or popover, adds no classes and never scrolls. You show the guidance yourself: a side panel, a chat message or your own tooltip component.

import { driver } from "driver.js/headless";

const tour = driver({
  steps: [
    { element: "#new-project", advanceOn: "click", data: { text: "Create a project" } },
    {
      element: "#project-name",
      advanceOn: { event: "input", when: element => element.value.length > 2 },
      data: { text: "Give it a name" },
    },
    { element: "#save", advanceOn: "click", waitForElement: 3000, data: { text: "Save it" } },
  ],
  onHighlighted: (element, step) => showGuide(element, step.data.text),
  onDestroyed: () => hideGuide(),
});

tour.drive();

See Build Your Own Tour UI for four complete examples with live demos.

It takes the same config and steps as driver.js and returns the same API, so you can switch a tour between the two. There is no stylesheet to import. The headless build is less than half the size of the full one.

What still works

  • Finding elements: selectors, elements and functions.
  • Missing elements: waitForElement, waitForRemovedElement, skipMissingElement, onElementMissing and onWaitingForElement.
  • onInteraction for every click, with region telling the highlighted element, the allowedElements and the rest of the page apart. Nothing is blocked unless it returns false.
  • advanceOn with when and strict, advanceDelay and advance().
  • Hooks: onHighlightStarted, onHighlighted, onDeselected, onDestroyStarted, onDestroyed, onInteraction, onWaitingForElement and onElementReplaced.
  • Navigation: drive(), moveNext(), movePrevious(), moveTo(), highlight() and destroy().
  • A highlighted element that your framework re-renders is followed, and advanceOn listens on the new one. onElementReplaced gets the new element, so your UI can move to it.

To show that a step is waiting for its element, use onWaitingForElement. Its signal aborts when the wait ends.

driver({
  waitForElement: 5000,
  onWaitingForElement: (element, step, opts) => {
    setLoading(true);
    opts.signal.addEventListener("abort", () => setLoading(false));
  },
});

getActiveElement() returns the current step’s element, or undefined for a step without one. onHighlighted runs as soon as the current call returns, not on an animation frame, so a tour keeps going in a background tab.

What it leaves to you

  • The overlay, popover and every option that styles them. updatePopover() and nudge() do nothing.
  • Scrolling. Call element.scrollIntoView() in onHighlighted if you want it.
  • Keyboard control. Arrow keys and Escape don’t move or close the tour.
  • Focus. It is not moved into a popover or back when the tour ends, and focus does nothing.
  • Blocking clicks. disableActiveInteraction and allowedElements are ignored. A strict advanceOn and an onInteraction that returns false still hold back clicks.

Starting a tour ends any other tour from the same build. A headless tour and a full one come from different builds, so they can run at the same time.

Without the headless build

If you use the full driver and only want it to stop scrolling, set scrollIntoView: false on the driver or on a step.