Configuration - Driver Js

import { CodeSample } from "../../components/CodeSample.tsx";

Driver.js is built to be highly configurable. You can configure the driver globally, or per step. You can also configure the driver on the fly, while it's running.

Configuration, steps, and state belong to the specific driver() instance you set them on. Each call to driver() is independent, so you can keep several instances on the same page and configuring or driving one never affects another.

Driver.js is written in TypeScript. Configuration options are mostly self-explanatory. Also, if you're using an IDE like WebStorm or VSCode, you'll get autocomplete and documentation for all the configuration options.

Driver Configuration

You can configure the driver globally by passing the configuration object to the driver call or by using the setConfig method. Given below are some of the available configuration options.

typescript

type Config = {
  // Array of steps to highlight. You should pass
  // this when you want to setup a product tour.
  steps?: DriveStep[];

  // Whether to animate the product tour. (default: true)
  animate?: boolean;
  // Duration of the transition animation in milliseconds. Controls both the
  // speed of the stage moving between steps and the overlay/popover fade-in.
  // Only applies when `animate` is true. (default: 400)
  duration?: number;
  // Overlay color. (default: black)
  // This is useful when you have a dark background
  // and want to highlight elements with a light
  // background color.
  overlayColor?: string;
  // Whether to smooth scroll to the highlighted element. (default: false)
  smoothScroll?: boolean;
  // Whether to allow closing the popover by clicking on the backdrop. (default: true)
  allowClose?: boolean;
  // Whether to allow scrolling the page while the driver is active.
  // Set to false to lock body scrolling for the duration of the tour. (default: true)
  allowScroll?: boolean;
  // Opacity of the backdrop. (default: 0.5)
  overlayOpacity?: number;
  // What to do when the overlay backdrop is clicked.
  // Possible options are 'close', 'nextStep', or a custom function. (default: 'close')
  overlayClickBehavior?:
    | "close"
    | "nextStep"
    | ((
        element?: Element,
        step: DriveStep,
        options: { config: Config; state: State; driver: Driver; index: number | undefined }
      ) => void);
  // Distance between the highlighted element and the cutout. (default: 10)
  stagePadding?: number;
  // Radius of the cutout around the highlighted element. (default: 5)
  stageRadius?: number;

  // Whether to allow keyboard navigation. (default: true)
  allowKeyboardControl?: boolean;

  // Whether to disable interaction with the highlighted element. (default: false)
  // Can be configured at the step level as well
  disableActiveInteraction?: boolean;

  // Advance the tour when the highlighted element is clicked, as if the next
  // button was pressed; onNextClick and onDoneClick still apply. The element's
  // own click behavior runs normally. Has no effect on steps where
  // disableActiveInteraction blocks clicks. Can be configured at the step
  // level. (default: false)
  advanceOnClick?: boolean;

  // Skip a step whose target element is specified but missing from the DOM,
  // moving on in the direction of travel instead of showing the centered
  // fallback popover. Steps without an element are intentional centered steps
  // and are never skipped. Can be configured at the step level. (default: false)
  skipMissingElement?: boolean;

  // Wait up to this many milliseconds for a step's element to appear before
  // treating it as missing (centered fallback popover, or a skip when
  // skipMissingElement is set). The current step stays highlighted while
  // waiting. Useful when the next element is rendered on demand, e.g. inside
  // a modal that the previous step's click opens. Can be configured at the
  // step level. (default: 0, off)
  waitForElement?: number;

  // If you want to add custom class to the popover
  popoverClass?: string;
  // Distance between the popover and the highlighted element. (default: 10)
  popoverOffset?: number;
  // Array of buttons to show in the popover. Defaults to ["next", "previous", "close"]
  // for product tours and [] for single element highlighting.
  showButtons?: AllowedButtons[];
  // Array of buttons to disable. This is useful when you want to show some of the
  // buttons, but disable some of them.
  disableButtons?: AllowedButtons[];

  // Whether to show the progress text in popover. (default: false)
  showProgress?: boolean;
  // Template for the progress text. You can use the following placeholders in the template:
  //  - {{current}}: The current step number
  //  - {{total}}: Total number of steps
  progressText?: string;

  // Text to show in the buttons. `doneBtnText`
  // is used on the last step of a tour.
  nextBtnText?: string;
  prevBtnText?: string;
  doneBtnText?: string;

  // Called after the popover is rendered.
  // PopoverDOM is an object with references to
  // the popover DOM elements such as buttons
  // title, descriptions, body, container etc.
  onPopoverRender?: (
    popover: PopoverDOM,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;

  // Hooks to run before and after highlighting
  // each step. Each hook receives the following
  // parameters:
  //   - element: The target DOM element of the step
  //   - step: The step object configured for the step
  //   - options.config: The current configuration options
  //   - options.state: The current state of the driver
  //   - options.driver: Current driver object
  //   - options.index: Index of the currently active step
  onHighlightStarted?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onHighlighted?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onDeselected?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;

  // Hooks to run before and after the driver
  // is destroyed. Each hook receives
  // the following parameters:
  //   - element: Currently active element
  //   - step: The step object configured for the currently active
  //   - options.config: The current configuration options
  //   - options.state: The current state of the driver
  //   - options.driver: Current driver object
  //   - options.index: Index of the currently active step
  onDestroyStarted?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onDestroyed?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;

  // Hooks to run on button clicks. Each hook receives
  // the following parameters:
  //   - element: The current DOM element of the step
  //   - step: The step object configured for the step
  //   - options.config: The current configuration options
  //   - options.state: The current state of the driver
  //   - options.driver: Current driver object
  //   - options.index: Index of the currently active step
  onNextClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onPrevClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onCloseClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  // Runs when the done button (the next button on the
  // last step of a tour) is clicked. When provided, it
  // runs instead of `onNextClick` on the last step.
  onDoneClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
};

Note: By overriding onNextClick, and onPrevClick hooks you control the navigation of the driver. This means that user won't be able to navigate using the buttons and you will have to either call driverObj.moveNext() or driverObj.movePrevious() to navigate to the next/previous step.

You can use this to implement custom logic for navigating between steps. This is also useful when you are dealing with dynamic content and want to highlight the next/previous element based on some logic.

onNextClick and onPrevClick hooks can be configured at the step level as well. When configured at the driver level, you control the navigation for all the steps. When configured at the step level, you control the navigation for that particular step only.

onDoneClick lets you detect when the user finishes the tour by clicking the done button on the last step. When provided, it runs instead of onNextClick on the last step, and Driver.js won't destroy the tour automatically; you control teardown by calling driverObj.destroy() yourself. Like the other click hooks, it can be configured at the driver or step level.

options.index: Every hook receives the zero-based index of the currently active step in options.index (equivalent to driverObj.getActiveIndex()), or undefined when driving a single highlight rather than a steps array. Note that index always reflects the active step, so inside onDeselected (which fires for the step being left during a transition) it points at the step being moved to, not the one being deselected.

The popover is the main UI element of Driver.js. It's the element that highlights the target element, and shows the step content. You can configure the popover globally, or per step. Given below are some of the available configuration options.

typescript

type Popover = {
  // Title and descriptions shown in the popover.
  // You can use HTML in these. Also, you can
  // omit one of these to show only the other.
  title?: string;
  description?: string;

  // Which side of the target element the popover is
  // placed on. Auto-flips to the opposite side when it
  // doesn't fit the viewport. (default: "bottom")
  side?: "top" | "right" | "bottom" | "left";
  // How the popover is aligned along that side. "start"
  // lines its leading edge up with the element, "center"
  // centers it, and "end" lines up the trailing edges.
  // (default: "start")
  align?: "start" | "center" | "end";

  // Array of buttons to show in the popover.
  // When highlighting a single element, there
  // are no buttons by default. When showing
  // a tour, the default buttons are "next",
  // "previous" and "close".
  showButtons?: ("next" | "previous" | "close")[];
  // An array of buttons to disable. This is
  // useful when you want to show some of the
  // buttons, but disable some of them.
  disableButtons?: ("next" | "previous" | "close")[];

  // Text to show in the buttons. `doneBtnText`
  // is used on the last step of a tour.
  nextBtnText?: string;
  prevBtnText?: string;
  doneBtnText?: string;

  // Whether to show the progress text in popover.
  showProgress?: boolean;
  // Template for the progress text. You can use
  // the following placeholders in the template:
  //   - {{current}}: The current step number
  //   - {{total}}: Total number of steps
  // Defaults to following if `showProgress` is true:
  //   - "{{current}} of {{total}}"
  progressText?: string;

  // Custom class to add to the popover element.
  // This can be used to style the popover.
  popoverClass?: string;

  // Hook to run after the popover is rendered.
  // You can modify the popover element here.
  // Parameter is an object with references to
  // the popover DOM elements such as buttons
  // title, descriptions, body, etc.
  onPopoverRender?: (
    popover: PopoverDOM,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;

  // Callbacks for button clicks. You can use
  // these to add custom behavior to the buttons.
  // Each callback receives the following parameters:
  //   - element: The current DOM element of the step
  //   - step: The step object configured for the step
  //   - options.config: The current configuration options
  //   - options.state: The current state of the driver
  //   - options.driver: Current driver object
  //   - options.index: Index of the currently active step
  onNextClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onPrevClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onCloseClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  // Runs instead of `onNextClick` when the done button
  // (the next button on the last step) is clicked.
  onDoneClick?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
};

Drive Step Configuration

Drive step is the configuration object passed to the highlight method or the steps array of the drive method. You can configure the popover and the target element for each step. Given below are some of the available configuration options.

typescript

type DriveStep = {
  // The target element to highlight.
  // This can be a DOM element,
  // a function that returns a DOM Element, or a CSS selector.
  // If this is a selector, the first matching
  // element will be highlighted.
  element?: Element | string | (() => Element);

  // The popover configuration for this step.
  // Look at the Popover Configuration section
  popover?: Popover;

  // Whether to disable interaction with the highlighted element. (default: false)
  disableActiveInteraction?: boolean;

  // Advance the tour when this step's highlighted element is clicked.
  // Overrides the driver-level option for this step. (default: false)
  advanceOnClick?: boolean;

  // Skip this step when its target element is specified but missing from the
  // DOM. Overrides the driver-level option for this step. (default: false)
  skipMissingElement?: boolean;

  // Wait up to this many milliseconds for this step's element to appear before
  // treating it as missing. Overrides the driver-level option. (default: 0, off)
  waitForElement?: number;

  // Arbitrary data that you can pass to the step in order to support complex custom logic in hooks.
  data?: Record<string, any>;

  // Callback when the current step is deselected,
  // about to be highlighted or highlighted.
  // Each callback receives the following parameters:
  //   - element: The current DOM element of the step
  //   - step: The step object configured for the step
  //   - options.config: The current configuration options
  //   - options.state: The current state of the driver
  //   - options.driver: Current driver object
  //   - options.index: Index of the currently active step
  onDeselected?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onHighlightStarted?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
  onHighlighted?: (
    element?: Element,
    step: DriveStep,
    options: { config: Config; state: State; driver: Driver; index: number | undefined }
  ) => void;
};

Hints Configuration

Hints are configured through the hints() factory from the driver.js/hints entry. See the Hints guide for an introduction and examples; the full options are given below.

typescript

type HintsConfig = {
  // Array of hints to show. See the Hint
  // Configuration section below for the format.
  hints?: DriverHint[];

  // Beacon defaults applied to every hint;
  // a hint's own beacon values win.
  beacon?: HintBeacon;

  // Text of the dismiss button. (default: "Got it")
  buttonText?: string;

  // Custom class and offset for the hint popovers,
  // same meaning as in tours.
  popoverClass?: string;
  popoverOffset?: number;

  // Dim the page while a hint is open, with the hint's
  // element cut out like a tour step. The popover then
  // anchors to the element instead of the beacon, the
  // open hint's beacon steps aside, and the other
  // beacons wait under the dim. Clicking the dimmed
  // page closes the hint. (default: false)
  overlay?: boolean;
  // Color and opacity of the dim. (defaults: "#000" and 0.7)
  overlayColor?: string;
  overlayOpacity?: number;

  // Called when a hint popover is opened, and when a
  // hint is dismissed (via the button or `dismiss()`).
  // Each hook receives the following parameters:
  //   - element: The hint's target DOM element
  //   - hint: The hint object
  //   - options.config: The hints configuration
  //   - options.hints: The hints instance
  onOpen?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
  onDismiss?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;

  // Runs instead of dismissing when the built-in button is clicked,
  // like a tour's onNextClick takes over the default advance. Call
  // options.hints.dismiss(hint.id) yourself to also remove the hint.
  // Can be configured per hint as well.
  onButtonClick?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
};

Hint Configuration

Each entry of the hints array describes one hint: the element it points at, the beacon that sits on it, and the popover that opens on click.

typescript

type DriverHint = {
  // The element the hint points at. This can be a DOM
  // element, a function that returns a DOM element, or
  // a CSS selector. A hint whose element is missing is
  // skipped, and picked up on the next show() if the
  // element has appeared since.
  element: Element | string | (() => Element);

  // Stable identity used by open/dismiss/restore and
  // passed to the hooks; useful for persisting
  // dismissals. Defaults to the hint's index.
  id?: string;

  // Where the beacon sits on the element's box, and
  // how it looks.
  beacon?: {
    // Edge of the element the beacon sits on. (default: "top")
    side?: "top" | "right" | "bottom" | "left";
    // Position along that edge. (default: "end")
    align?: "start" | "center" | "end";
    // Whether the beacon pulses. The pulse also pauses
    // automatically for users who prefer reduced
    // motion. (default: true)
    animate?: boolean;
    // Custom class for the beacon, e.g. to scope the
    // --driver-hint-size and --driver-hint-color
    // CSS variables to it.
    className?: string;
  };

  // The popover that opens when the beacon is clicked.
  // Rendered exactly like a tour popover.
  popover?: {
    title?: string;
    description?: string;
    side?: "top" | "right" | "bottom" | "left";
    align?: "start" | "center" | "end";
    popoverClass?: string;

    // The dismiss button. Hide it for hints you only
    // dismiss from code. (default: true)
    showButton?: boolean;
    // Overrides the instance-level buttonText.
    buttonText?: string;
    // Overrides the instance-level onButtonClick.
    onButtonClick?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;

    // Hook to run after the popover is rendered,
    // same as in tours but with the hint and the
    // hints instance in the options.
    onPopoverRender?: (popover: PopoverDOM, options: { hint: DriverHint; hints: Hints }) => void;
  };

  // Hint-level hooks, taking precedence over the
  // instance-level ones.
  onOpen?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;
  onDismiss?: (element: Element, hint: DriverHint, options: { config: HintsConfig; hints: Hints }) => void;

  // Arbitrary data to carry along, available wherever
  // the hint object is.
  data?: Record<string, any>;
};

State

You can access the current state of the driver by calling the getState method. It's also passed to the hooks and callbacks.

typescript

type State = {
  // Whether the driver is currently active or not
  isInitialized?: boolean;

  // Index of the currently active step if using
  // as a product tour and have configured the
  // steps array.
  activeIndex?: number;
  // DOM element of the currently active step
  activeElement?: Element;
  // Step object of the currently active step
  activeStep?: DriveStep;

  // DOM element that was previously active
  previousElement?: Element;
  // Step object of the previously active step
  previousStep?: DriveStep;

  // DOM elements for the popover i.e. including
  // container, title, description, buttons etc.
  popover?: PopoverDOM;
};