# Build Your Own Tour UI

> Four tours with completely different UIs, built on driver.js/headless: a checklist panel, a chat assistant, a hand-drawn spotlight and hints inside a form. Live demos with the full code.

Use this when the popover isn't the right shape for your product. With [`driver.js/headless`](https://driverjs.com/docs/headless-tours.md), 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 popover | [Match Your Brand](https://driverjs.com/docs/match-your-brand.md), [Theming](https://driverjs.com/docs/theming.md) |
| Add, rename or translate buttons | [Custom Buttons](https://driverjs.com/docs/custom-buttons.md) |
| Change the popover's markup | [`onPopoverRender`](https://driverjs.com/docs/popover.md#event-handlers) |
| Draw everything yourself | `driver.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:

```js
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.

- `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.

- `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.

- `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.

- `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`](https://driverjs.com/docs/headless-tours.md), [`advanceOn`](https://driverjs.com/docs/action-driven-tours.md), [`waitForElement` and `onWaitingForElement`](https://driverjs.com/docs/configuration.md#missing-elements), [hooks](https://driverjs.com/docs/configuration.md#hooks), [navigation](https://driverjs.com/docs/api.md#navigation)
