Driver.js

Driver.js is a lightweight (~5kb gzipped), dependency-free library designed for creating product tours, feature introductions, and various page overlays. Unlike traditional tour libraries, it is highly versatile and can be used for:

• Highlighting elements: Focus user attention on specific page components.
• Contextual help: Displaying popovers with a dimmed background (e.g., during form filling).
• Focus shifting: Directing user attention to specific areas.
• Simulating 'Turn off the Lights' widgets: Dimming the background to highlight content.
• Modals: Using it as a simple modal implementation.
• Product Tours: Step-by-step guided walkthroughs.

Key features include full keyboard control, TypeScript support, and hooks to manipulate elements during highlight/deselection lifecycles.

Driver.js distinguishes between closing a popover and dismissing a hint:

• Closing: Occurs when clicking the beacon again, clicking outside the popover, or pressing <kbd>Escape</kbd>. The popover disappears, but the beacon remains on the page and can be reopened.
• Dismissing: Occurs when the user clicks the dismissal button (defaults to "Got it"). This removes the beacon entirely for the session and triggers the onDismiss hook.

To take control of the dismissal button behavior, use the onButtonClick option.

Driver.js configuration can be applied at three levels:

1. Globally: By passing a configuration object to the driver() call.
2. Per Step: By defining specific options within an individual DriveStep object.
3. On the fly: By using the setConfig method while the driver is running.

Each call to driver() creates an independent instance. Configuration, steps, and state belong to that specific instance, meaning you can run multiple independent tours on the same page without them interfering with each other.

You can display the current step progress in the bottom left corner of the screen by enabling the showProgress option. By default, this option is set to false.

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

const driverObj = driver({
  showProgress: true,
  showButtons: ['next', 'previous'],
  steps: [
    { element: '#step-1', popover: { title: 'Step 1', description: 'Description' } },
    { element: '#step-2', popover: { title: 'Step 2', description: 'Description' } },
  ]
});

driverObj.drive();

You can customize the popover's appearance by applying a custom class via the popoverClass option. This can be set globally in the main driver configuration or specifically for an individual step.

// Global configuration
const driverObj = driver({
  popoverClass: "my-custom-popover-class",
});

// Step-specific configuration
const driverObj2 = driver({
  steps: [
    {
      element: "#some-element",
      popover: {
        title: "Title",
        description: "Description",
        popoverClass: "my-custom-popover-class",
      },
    },
  ],
});

To force users to complete a tour before they can exit, set the allowClose option to false in the driver() configuration object. When allowClose is false, the user cannot close the tour (e.g., by clicking the overlay or using escape keys) until they reach and complete the final step of the tour.

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

const driverObj = driver({
  showProgress: true,
  allowClose: false,
  steps: [
    { element: '#prevent-exit', popover: { title: 'Step 1', description: 'Description' } },
    { popover: { title: 'Final Step', description: 'The tour ends here.' } }
  ],
});

driverObj.drive();

When using the CDN version, the library is not available via imports. Instead, you must access the driver and hints functions through the window object using the specific namespaces window.driver.js.driver and window.driverHints.hints.

// Accessing the driver
const driver = window.driver.js.driver;
const driverObj = driver();

driverObj.highlight({
  element: "#some-element",
  popover: {
    title: "Title",
    description: "Description",
  },
});

// Accessing hints
const hints = window.driverHints.hints;

Hints and tours can coexist. When a tour is active, beacons are hidden and any open hint popover is closed. Once the tour ends, beacons reappear.

A common pattern is using a hint to launch a tour by overriding the onButtonClick handler in the hint's popover configuration.

const tour = driver({ steps: [...] });

const productHints = hints({
  hints: [
    {
      element: "#whats-new",
      id: "whats-new",
      popover: {
        title: "New dashboard",
        description: "Want a quick walkthrough?",
        buttonText: "Take the tour",
        onButtonClick: (element, hint, { hints: instance }) => {
          instance.close();
          tour.drive();
        },
      },
    },
  ],
});

You can change the appearance of the Driver.js backdrop by using the overlayColor and overlayOpacity options in the driver() configuration object.

• overlayColor: Accepts any valid CSS color string (e.g., 'red', 'blue', '#ff0000', or RGB values).
• overlayOpacity: Controls the dimming effect of the backdrop.

These options can be applied globally when initializing the driver instance or specifically within tour steps.

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

const driverObj = driver({
  overlayColor: 'red',
  overlayOpacity: 0.3
});

driverObj.highlight({
  popover: {
    title: 'Custom Overlay',
    description: 'The overlay is now red with 0.3 opacity.'
  }
});

Driver.js manages dismissals in memory for the current session but does not persist them to storage automatically. To remember that a user has dismissed a hint across page reloads, use the onDismiss hook to save the hint's id to localStorage and filter the hints array when initializing the instance.

const dismissed = new Set(JSON.parse(localStorage.getItem("hints") ?? "[]"));

const productHints = hints({
  hints: allHints.filter(hint => !dismissed.has(hint.id)),
  onDismiss: (element, hint) => {
    dismissed.add(hint.id);
    localStorage.setItem("hints", JSON.stringify([...dismissed]));
  },
});

productHints.show();