Migrate to 1.x

Driver.js 1.x has a new API. This page lists what changed since 0.x. The current options are in Configuration, the methods in the API Reference.

Import

- import Driver from 'driver.js';
- import 'driver.js/dist/driver.min.css';
+ import { driver } from "driver.js";
+ import "driver.js/dist/driver.css";

Initialization

- const driverObj = new Driver(config);
- driverObj.defineSteps(steps);
+ const driverObj = driver({ ...config, steps });

Configuration

const config = {
-  overlayClickNext: false,
+  overlayClickBehavior: "close", // or "nextStep", "none", a function
-  closeBtnText: 'Close', // Removed: the close button is an icon
-  scrollIntoViewOptions: {}, // Removed: see smoothScroll
-  opacity: 0.75,
+  overlayOpacity: 0.75,
-  className: 'scoped-class',
+  popoverClass: 'scoped-class',
-  padding: 10,
+  stagePadding: 10,
-  showButtons: false,
+  showButtons: ["next", "previous", "close"], // [] for none
-  keyboardControl: true,
+  allowKeyboardControl: true,

-  onHighlightStarted: (Element) => {},
-  onHighlighted: (Element) => {},
-  onDeselected: (Element) => {},
+  // Every hook now gets (element, step, { config, state, driver, index })
+  onHighlightStarted: (element, step, opts) => {},
+  onHighlighted: (element, step, opts) => {},
+  onDeselected: (element, step, opts) => {},

-  onReset: (Element) => {},
+  onDestroyStarted: (element, step, opts) => {},
+  onDestroyed: (element, step, opts) => {},
+  onCloseClick: (element, step, opts) => {},

-  onNext: (Element) => {},
-  onPrevious: (Element) => {},
+  // These replace the default: call moveNext() / movePrevious() yourself
+  onNextClick: (element, step, opts) => {},
+  onPrevClick: (element, step, opts) => {},

+  // New
+  overlayColor: "#000",
+  stageRadius: 5,
+  popoverOffset: 10,
+  disableButtons: ["previous"],
+  showProgress: true,
+  progressText: "{{current}} of {{total}}",
+  onPopoverRender: (popover, opts) => {},
}

Steps and Popovers

const step = {
-  element: '.some-element', // Required
+  element: '.some-element', // Optional: centered without it
  popover: {
-    closeBtnText: 'Close', // Removed
-    className: 'popover-class',
+    popoverClass: 'popover-class',
-    showButtons: false,
+    showButtons: ["next", "previous", "close"],
-    title: '', // Required
-    description: '', // Required
+    title: '', // Optional
+    description: '', // Optional

-    // left, left-center, left-bottom, top, top-center, top-right,
-    // right, right-center, right-bottom, bottom, bottom-center,
-    // bottom-right, mid-center
-    position: 'left',
+    side: "left", // "top" | "right" | "bottom" | "left"
+    align: "start", // "start" | "center" | "end"

+    // New
+    showProgress: true,
+    progressText: "{{current}} of {{total}}",
+    onPopoverRender: (popover, opts) => {},
+    onNextClick: (element, step, opts) => {},
+    onPrevClick: (element, step, opts) => {},
+    onCloseClick: (element, step, opts) => {},
  },

+  // New: per-step hooks
+  onHighlightStarted: (element, step, opts) => {},
+  onHighlighted: (element, step, opts) => {},
+  onDeselected: (element, step, opts) => {},
};

Methods

- driverObj.preventMove(); // Removed: use onNextClick + moveNext()
- activeElement.getCalculatedPosition();
- activeElement.hidePopover();
- activeElement.showPopover();
- activeElement.getNode();

- const isActivated = driverObj.isActivated;
+ const isActivated = driverObj.isActive();

- driverObj.start(stepNumber);
+ driverObj.drive(stepNumber);

- driverObj.highlight(string | stepDefinition);
+ driverObj.highlight(stepDefinition);

- driverObj.reset();
+ driverObj.destroy();

- driverObj.hasHighlightedElement();
+ driverObj.getActiveElement() !== undefined;

- driverObj.getHighlightedElement();
+ driverObj.getActiveElement();

- driverObj.getLastHighlightedElement();
+ driverObj.getPreviousElement();

+ // New
+ driverObj.moveTo(stepIndex);
+ driverObj.getActiveStep();
+ driverObj.getPreviousStep();
+ driverObj.isLastStep();
+ driverObj.isFirstStep();
+ driverObj.getState();
+ driverObj.getConfig();
+ driverObj.setConfig(config);
+ driverObj.refresh();