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,onElementMissingandonWaitingForElement. onInteractionfor every click, withregiontelling the highlighted element, theallowedElementsand the rest of the page apart. Nothing is blocked unless it returnsfalse.advanceOnwithwhenandstrict,advanceDelayandadvance().- Hooks:
onHighlightStarted,onHighlighted,onDeselected,onDestroyStarted,onDestroyed,onInteraction,onWaitingForElementandonElementReplaced. - Navigation:
drive(),moveNext(),movePrevious(),moveTo(),highlight()anddestroy(). - A highlighted element that your framework re-renders is followed, and
advanceOnlistens on the new one.onElementReplacedgets 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()andnudge()do nothing. - Scrolling. Call
element.scrollIntoView()inonHighlightedif 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
focusdoes nothing. - Blocking clicks.
disableActiveInteractionandallowedElementsare ignored. AstrictadvanceOnand anonInteractionthat returnsfalsestill 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.
driver.js