Build Your Own Tour UI

Use this when the popover isn’t the right shape for your product. With driver.js/headless, driver.js still runs the tour: it finds each element, waits for it and notices when the user does the step. Everything you see is yours.

The four tours below use the same engine with four very different UIs. The code under each demo is the exact code it runs.

How Far to Go

You want to…Use
Use your colors and fonts on the popoverMatch Your Brand, Theming
Add, rename or translate buttonsCustom Buttons
Change the popover’s markuponPopoverRender
Draw everything yourselfdriver.js/headless, on this page

The Pattern

Every headless UI is built from the same few hooks. Put your content in data on each step and render it when the step starts:

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

const tour = driver({
  steps: [{ element: "#save", advanceOn: "click", data: { text: "Save it" } }],
  onHighlighted: (element, step, opts) => show(element, step.data, opts.index),
  onDeselected: element => unmark(element),
  onWaitingForElement: (element, step, opts) => showLoading(opts.signal),
  onDestroyed: () => hide(),
});

tour.drive();

Your own buttons call tour.moveNext(), tour.movePrevious() and tour.destroy(). Steps with advanceOn move on by themselves when the user does the thing.

Checklist Panel

The guide is a panel beside the app that ticks off steps as the user does them. Nothing covers the page, and the current target gets an outline from your own CSS class.

Your guide shows up here.

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

const steps = [
  {
    element: "#hp-new",
    advanceOn: "click",
    data: { title: "Start a project" },
  },
  {
    element: "#hp-name",
    advanceOn: {
      event: "input",
      when: element => element.value.trim().length > 2,
    },
    data: { title: "Give it a name" },
  },
  {
    element: "#hp-create",
    advanceOn: "click",
    data: { title: "Create it" },
  },
];

export function startPanelTour(panel) {
  panel.setAttribute("aria-live", "polite");

  const tour = driver({
    steps,
    onHighlighted: (element, step, opts) => {
      element?.classList.add("is-guided");
      renderPanel(panel, opts.index);
    },
    onElementReplaced: element => {
      element.classList.add("is-guided");
    },
    onDeselected: element => {
      element?.classList.remove("is-guided");
    },
    onDestroyed: (element, step, opts) => {
      renderPanel(panel, opts.reason === "done" ? steps.length : -1);
    },
  });

  tour.drive();
  return tour;
}

function renderPanel(panel, current) {
  const done = Math.max(current, 0);
  const items = steps.map((step, index) => {
    const state = index < current ? "done" : index === current ? "current" : "";
    return `<li class="${state}">${step.data.title}</li>`;
  });

  panel.innerHTML = `
    <p class="panel-count">${done} of ${steps.length} done</p>
    <div class="panel-bar" style="--done: ${done / steps.length}"></div>
    <ol>${items.join("")}</ol>
  `;
}
  • onHighlighted adds a class to the element and redraws the panel. opts.index is the current step.
  • onDeselected takes the class off again, also when the tour ends. If your framework re-renders the button, onElementReplaced puts the class on the new one.
  • opts.reason === "done" in onDestroyed tells a finished tour from a closed one.

Chat Assistant

Each step arrives as a chat message. Upload takes a moment, so the assistant shows that it’s waiting until the Share button appears.

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

export function startAssistantTour(chat) {
  chat.setAttribute("role", "log");

  const say = (html, kind = "bot") => {
    const message = document.createElement("p");
    message.className = `chat-message ${kind}`;
    message.innerHTML = html;
    chat.append(message);
    chat.scrollTop = chat.scrollHeight;
    return message;
  };

  const tour = driver({
    steps: [
      {
        element: "#ha-upload",
        advanceOn: "click",
        data: { say: "Hi! Let's share a file. Click <b>Upload</b>." },
      },
      {
        element: "#ha-share",
        waitForElement: 5000,
        advanceOn: "click",
        data: { say: "It's up. Now click <b>Share</b> next to it." },
      },
      {
        element: "#ha-copy",
        advanceOn: "click",
        data: { say: "Last one: <b>Copy link</b>." },
      },
    ],
    onHighlightStarted: (element, step) => {
      say(step.data.say);
    },
    onWaitingForElement: (element, step, opts) => {
      const typing = say("Uploading…", "typing");
      opts.signal.addEventListener("abort", () => typing.remove());
    },
    onDestroyed: (element, step, opts) => {
      say(opts.reason === "done" ? "All set! 🎉" : "Talk later 👋");
    },
  });

  tour.drive();
  return tour;
}
  • onHighlightStarted posts the step’s message as soon as its element is found.
  • waitForElement holds the tour while the upload runs. onWaitingForElement shows “Uploading…”, and its signal removes it when the wait ends.
  • The same setup works for an AI assistant: put the step text in data and let your chat render it.

Hand-Drawn Spotlight

Your own highlight: a dashed ring that glides between elements, with a sticky note and your own buttons and keys. No overlay and no popover from driver.js.

Visits1,204
Sales$8,310
import { driver } from "driver.js/headless";

const steps = [
  { element: "#hs-visits", data: { text: "Visits, live." } },
  { element: "#hs-sales", data: { text: "Sales this week." } },
  { element: "#hs-chart", data: { text: "Your trend at a glance." } },
];

export function startSpotlightTour() {
  const ring = document.createElement("div");
  ring.className = "spot-ring";
  const note = document.createElement("div");
  note.className = "spot-note";
  note.innerHTML = `
    <p></p>
    <small></small>
    <button data-go="back">Back</button>
    <button data-go="next">Next</button>
  `;
  document.body.append(ring, note);

  const [text, count, back, next] = note.children;

  const tour = driver({
    steps,
    onHighlighted: (element, step, opts) => {
      element.scrollIntoView({ block: "nearest" });
      place();

      text.textContent = step.data.text;
      count.textContent = `${opts.index + 1} / ${steps.length}`;
      back.hidden = opts.driver.isFirstStep();
      next.textContent = opts.driver.isLastStep() ? "Done" : "Next";
    },
    onDestroyed: () => {
      listeners.abort();
      ring.remove();
      note.remove();
    },
  });

  function place() {
    const target = tour.getActiveElement();
    if (!target) {
      return;
    }

    const rect = target.getBoundingClientRect();
    ring.style.translate = `${rect.left - 8}px ${rect.top - 8}px`;
    ring.style.width = `${rect.width + 16}px`;
    ring.style.height = `${rect.height + 16}px`;
    note.style.translate = `${rect.left}px ${rect.bottom + 18}px`;
  }

  const listeners = new AbortController();
  const { signal } = listeners;
  window.addEventListener("scroll", place, { capture: true, signal });
  window.addEventListener("resize", place, { signal });

  back.addEventListener("click", () => tour.movePrevious());
  next.addEventListener("click", () => tour.moveNext());

  window.addEventListener(
    "keydown",
    event => {
      const isTyping = event.target.closest?.("input, textarea, select");
      if (isTyping || event.metaKey || event.ctrlKey || event.altKey) {
        return;
      }

      if (event.key === "ArrowRight") {
        tour.moveNext();
      } else if (event.key === "ArrowLeft" && !tour.isFirstStep()) {
        tour.movePrevious();
      } else if (event.key === "Escape") {
        tour.destroy();
      }
    },
    { signal }
  );

  tour.drive();
  return tour;
}
  • getBoundingClientRect() on tour.getActiveElement() places the ring, so it stays on the element even after a re-render. A CSS transition on translate, width and height makes it glide.
  • The note’s buttons are built once and only their text changes, so keyboard focus stays on Next between steps.
  • The headless build doesn’t scroll or listen to keys, so the code does both: scrollIntoView(), then the arrow keys and Escape, skipped while the user types in a field.
  • One AbortController removes every listener in onDestroyed.

Hints Inside a Form

The guidance is part of the form: a line of help under the current field, and the tour moves on when the field is filled in correctly. Sign up unlocks at the end.

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

export function startInlineTour() {
  const hint = document.createElement("p");
  hint.className = "inline-hint";
  hint.id = "tour-hint";

  const tour = driver({
    steps: [
      {
        element: "#hi-email",
        advanceOn: {
          event: "change",
          when: element => element.checkValidity(),
        },
        data: { hint: "Your work email. Press Tab when you're done." },
      },
      {
        element: "#hi-password",
        advanceOn: {
          event: "input",
          when: element => element.value.length >= 8,
        },
        data: { hint: "At least 8 characters. Keep typing…" },
      },
      {
        element: "#hi-terms",
        advanceOn: {
          event: "change",
          when: element => element.checked,
        },
        data: { hint: "Tick this one and you're in." },
      },
    ],
    onHighlighted: (element, step) => {
      hint.textContent = step.data.hint;
      element.closest(".field").append(hint);
      element.setAttribute("aria-describedby", hint.id);
    },
    onDeselected: element => {
      element?.removeAttribute("aria-describedby");
    },
    onDestroyed: (element, step, opts) => {
      hint.remove();
      if (opts.reason === "done") {
        document.querySelector("#hi-submit").disabled = false;
      }
    },
  });

  tour.drive();
  return tour;
}
  • advanceOn with when checks the field and moves on once it’s right. The email waits for change, so the tour doesn’t jump ahead mid-address. The password checks on every keystroke.
  • onHighlighted moves one hint element into the current field and links it with aria-describedby, so screen readers read it too. Focus stays where the user put it.
  • :has(.inline-hint) styles the current field with plain CSS.

Uses: driver.js/headless, advanceOn, waitForElement and onWaitingForElement, hooks, navigation