Driverjs

Driver.js API リファレンス

Driver.js 公式ドキュメントの全 API を網羅したスキル。 ユーザーのタスクに応じて適切な README.md を読み、そこから個別ファイルへ辿ること。

ディレクトリ構造

.claude/skills/driverjs/
├── SKILL.md                                    ← このファイル（エントリーポイント）
└── references/
    ├── getting-started/README.md               ← インストール・基本操作（2ページ）
    ├── api/README.md                           ← 設定・メソッド・テーマ（3ページ）
    ├── examples/README.md                      ← ユースケース別サンプル（4ページ）
    └── migration/README.md                     ← バージョン移行（1ページ）

探索手順

1. ユーザーのタスクに最も関連するカテゴリを特定する 2. そのカテゴリの README.md を読む 3. README.md 内の一覧から必要な個別ファイルを選んで読む 4. 必要に応じて関連ページのリンクを辿る

カテゴリ → README.md マッピング

Configuration

Driver.js accepts a configuration object when creating a driver instance. Options can be set at the driver level (global) and overridden at the step level.

Config Type (Driver-Level Options)

const driverObj = driver({
  steps: [/* ... */],
  animate: true,
  overlayColor: 'black',
  smoothScroll: false,
  allowClose: true,
  showProgress: true,
  onHighlighted: (element, step, options) => { /* ... */ },
});

Driver Hooks / Callbacks

Hooks can be set at the driver level (apply to all steps) or at the step level (override driver-level).

When overriding onNextClick or onPrevClick, automatic navigation is disabled. You must manually call driverObj.moveNext() or driverObj.movePrevious() to advance:

const driverObj = driver({
  onNextClick: (element, step, { config, state }) => {
    // Custom logic before advancing
    driverObj.moveNext();
  },
});

Popover Type (Per-Step Popover Config)

Each step's popover property accepts these options, overriding the driver-level defaults:

DriveStep Type

Each entry in the steps array has the following shape:

const steps = [
  {
    element: '#my-element',
    popover: {
      title: 'Feature',
      description: 'This is a feature.',
      side: 'bottom',
      align: 'start',
    },
  },
  {
    element: () => document.querySelector('.dynamic-el'),
    popover: { title: 'Dynamic', description: 'Resolved at runtime.' },
    onHighlighted: (element, step, options) => {
      console.log('Highlighted:', element);
    },
  },
];

Omitting element displays the popover as a centered modal without highlighting any element.

State Type

The state object passed to hooks and available via getState():

type State = {
  isInitialized?: boolean;
  activeIndex?: number;
  activeElement?: Element;
  activeStep?: DriveStep;
  previousElement?: Element;
  previousStep?: DriveStep;
  popover?: PopoverDOM;
};

Related

• Methods
• Theming

Methods

All methods are called on the driver instance returned by driver().

Initialization

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

const driverObj = driver({
  steps: [
    { element: '#step1', popover: { title: 'Step 1', description: 'First step' }},
    { element: '#step2', popover: { title: 'Step 2', description: 'Second step' }},
  ],
});

Tour Control

driverObj.drive();      // Start from the beginning
driverObj.drive(2);     // Start from step index 2
driverObj.moveNext();   // Advance one step
driverObj.moveTo(0);    // Jump back to the first step

Navigation Checks

Step Information

Status

Configuration

driverObj.setConfig({ animate: false });
driverObj.setSteps([
  { element: '#new-step', popover: { title: 'New', description: 'Replaced steps' }},
]);
driverObj.drive();

State & Highlighting

// Single element highlight
driverObj.highlight({
  element: '#feature',
  popover: { title: 'Feature', description: 'Check this out.' },
});

// Refresh after layout change
window.addEventListener('resize', () => {
  driverObj.refresh();
});

Cleanup

driverObj.destroy();

Related

• Configuration
• Theming

Driver.js — API

Theming

Driver.js can be styled using plain CSS. All popover and overlay elements use stable CSS class names that can be targeted directly or scoped via the popoverClass option.

CSS Classes

Using popoverClass

Apply a custom CSS class to scope styles to specific driver instances or steps:

// Driver-level — applies to all steps
const driverObj = driver({
  popoverClass: 'my-theme',
  steps: [/* ... */],
});

// Step-level — applies to a single step
const driverObj = driver({
  steps: [
    {
      element: '#step1',
      popover: {
        title: 'Styled Step',
        description: 'This step has a custom theme.',
        popoverClass: 'step-theme',
      },
    },
  ],
});

.my-theme .driver-popover-title {
  color: #1a73e8;
}

.my-theme .driver-popover-description {
  font-size: 14px;
}

Using onPopoverRender

For advanced customization, use the onPopoverRender callback to directly manipulate the popover DOM after rendering. The callback receives a PopoverDOM object:

const driverObj = driver({
  onPopoverRender: (popover, { config, state }) => {
    // Add a custom button to the footer
    const customBtn = document.createElement('button');
    customBtn.innerText = 'Skip Tour';
    customBtn.addEventListener('click', () => driverObj.destroy());
    popover.footerButtons.appendChild(customBtn);
  },
});

Notes

• For practical styling examples with full CSS snippets, see Styling Examples
• Always import driver.js/dist/driver.css as the base stylesheet before applying custom themes
• The popoverClass approach is preferred for simple styling; onPopoverRender is for DOM-level customization
• Step-level popoverClass overrides the driver-level value (it does not merge)

Related

• Configuration
• Methods

Async Tour & Lifecycle Control

Patterns for controlling tour flow with async operations, exit confirmation, and forced completion.

Async Tour

Override onNextClick to perform async operations before advancing. When overriding navigation hooks, you must manually call moveNext() or movePrevious().

const driverObj = driver({
  showProgress: true,
  steps: [
    {
      element: '#element1',
      popover: { title: 'Step 1', description: 'First step' },
      onNextClick: async () => {
        // Fetch data or perform async operations
        const data = await fetchData();
        // Dynamically add element to DOM
        document.body.appendChild(createDynamicElement(data));
        driverObj.moveNext();
      }
    },
    {
      element: '#dynamic-element',
      popover: { title: 'Dynamic Step', description: 'This element was added dynamically' },
      onDeselected: () => {
        // Clean up dynamic element when leaving step
        document.getElementById('dynamic-element')?.remove();
      }
    },
    { element: '#element3', popover: { title: 'Final Step', description: 'Done' }}
  ]
});

driverObj.drive();

Hooks can be set at driver level (all steps) or step level (individual step only).

Confirm on Exit

Use onDestroyStarted to intercept tour exit and show a confirmation dialog.

const driverObj = driver({
  showProgress: true,
  steps: [/* ... */],
  onDestroyStarted: () => {
    if (!driverObj.hasNextStep() || confirm("Are you sure?")) {
      driverObj.destroy();
    }
  },
});

driverObj.drive();

When overriding onDestroyStarted, you are responsible for calling driverObj.destroy() to actually exit the tour.

Prevent Tour Exit

Set allowClose to false to prevent users from closing the tour before completing all steps.

const driverObj = driver({
  allowClose: false,
  showProgress: true,
  steps: [/* ... */]
});

driverObj.drive();

Notes

• onNextClick / onPrevClick at step level override only that step; at driver level they override all steps
• When overriding onDestroyStarted, the tour will not close unless you call destroy() explicitly
• allowClose: false disables closing via backdrop click and the close button

Related

• Configuration — Hooks
• Methods

Highlight & Popover

Popover positioning, button customization, and single-element highlight patterns.

Popover Position

Control placement with side and align options:

driverObj.highlight({
  element: '#element',
  popover: {
    title: 'Title',
    description: 'Description',
    side: 'left',
    align: 'start'
  }
});

The popover automatically repositions to fit within the viewport if the specified position doesn't fit.

Popover Buttons

Show / Hide Buttons

const driverObj = driver({
  showButtons: ['next', 'previous', 'close'],
  disableButtons: ['previous'],
  steps: [/* ... */]
});

Custom Button Text

const driverObj = driver({
  nextBtnText: '-->',
  prevBtnText: '<--',
  doneBtnText: 'x',
  steps: [/* ... */]
});

Custom Buttons via onPopoverRender

const driverObj = driver({
  onPopoverRender: (popover, { config, state }) => {
    const btn = document.createElement("button");
    btn.innerText = "Custom Action";
    popover.footerButtons.appendChild(btn);
    btn.addEventListener("click", () => { /* ... */ });
  },
  steps: [/* ... */]
});

When using highlight() for a single element, only the close button is shown by default.

Simple Highlight

Use highlight() for single-element highlighting without a full tour:

const driverObj = driver({
  popoverClass: 'my-theme',
  stagePadding: 4,
});

driverObj.highlight({
  element: '#highlight-me',
  popover: {
    side: 'bottom',
    title: 'Feature Name',
    description: 'This is an important feature.'
  }
});

Modal Without Element

Omit element to show a centered modal popover:

driverObj.highlight({
  popover: {
    title: 'Welcome',
    description: '<img src="welcome.png" /><p>Welcome to our app!</p>'
  }
});

Form Field Contextual Help

Attach highlights to focus events for contextual form assistance:

const driverObj = driver({
  stagePadding: 0,
  onDestroyed: () => { document?.activeElement?.blur(); }
});

document.getElementById('name').addEventListener('focus', () => {
  driverObj.highlight({
    element: '#name',
    popover: { title: 'Name', description: 'Enter your full name' }
  });
});

Related

• Configuration
• Theming

Driver.js — Examples

Styling

Customizing the appearance of popovers and overlays in Driver.js.

Popover Styling with CSS

Apply a custom class via popoverClass and target Driver.js CSS classes. For the complete list of CSS class names, see Theming.

const driverObj = driver({
  popoverClass: 'my-theme'
});

Per-step styling:

{
  element: '#element',
  popover: {
    title: 'Title',
    description: 'Description',
    popoverClass: 'step-specific-theme'
  }
}

Example CSS:

.driver-popover.my-theme {
  background-color: #fde047;
  color: #000;
}

.driver-popover.my-theme .driver-popover-title {
  font-size: 20px;
}

.driver-popover.my-theme .driver-popover-description {
  font-size: 14px;
}

.driver-popover.my-theme button {
  background-color: #000;
  color: #fde047;
  border-radius: 4px;
  padding: 5px 10px;
}

.driver-popover.my-theme .driver-popover-close-btn {
  color: #000;
}

Popover Styling with onPopoverRender

For advanced DOM manipulation, use the onPopoverRender callback:

const driverObj = driver({
  onPopoverRender: (popover, { config, state }) => {
    const customButton = document.createElement("button");
    customButton.innerText = "Go to First";
    popover.footerButtons.appendChild(customButton);
    customButton.addEventListener("click", () => {
      driverObj.drive(0);
    });
  },
  steps: [/* ... */]
});

PopoverDOM properties: wrapper, arrow, title, description, footer, progress, previousButton, nextButton, closeButton, footerButtons.

Overlay Styling

Customize the overlay with overlayColor and overlayOpacity:

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

driverObj.highlight({
  element: '#element',
  popover: {
    title: 'Custom Overlay',
    description: 'Red overlay with 70% opacity'
  }
});

These options apply to both highlight() and tour steps.

Related

• Theming
• Configuration

Tours

Examples of multi-step tour configurations in Driver.js.

Animated Tour (Default)

By default, Driver.js animates transitions between tour steps.

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

const driverObj = driver({
  showProgress: true,
  steps: [
    { element: '#element1', popover: { title: 'Step 1', description: 'First step', side: 'left', align: 'start' }},
    { element: '#element2', popover: { title: 'Step 2', description: 'Second step', side: 'bottom', align: 'start' }},
    { element: '#element3', popover: { title: 'Step 3', description: 'Third step', side: 'right', align: 'start' }},
  ]
});

driverObj.drive();

Static Tour

Set animate to false for instant transitions without animation.

const driverObj = driver({
  animate: false,
  showProgress: false,
  showButtons: ['next', 'previous', 'close'],
  steps: [
    { element: '#element1', popover: { title: 'Step 1', description: 'Description', side: 'bottom', align: 'start' }},
    { element: '#element2', popover: { title: 'Step 2', description: 'Description', side: 'top', align: 'start' }},
  ]
});

driverObj.drive();

Tour Progress

Enable the built-in progress indicator with showProgress and customize with progressText.

const driverObj = driver({
  showProgress: true,
  progressText: '{{current}} / {{total}}',
  steps: [/* ... */]
});

Related

• Configuration
• Methods

Basic Usage

Driver.js provides two primary methods for guiding users: multi-step tours and single element highlighting.

Multi-Step Tour

Create a driver instance with a steps array and call drive() to start:

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

const driverObj = driver({
  showProgress: true,
  steps: [
    { element: '#step1', popover: { title: 'Step 1', description: 'Description for step 1' }},
    { element: '#step2', popover: { title: 'Step 2', description: 'Description for step 2' }},
    { element: '#step3', popover: { title: 'Step 3', description: 'Description for step 3' }},
  ]
});

driverObj.drive();

Each step targets a DOM element via CSS selector and displays a popover with a title and description.

Single Element Highlight

Use the highlight() method to focus on a single element:

const driverObj = driver();

driverObj.highlight({
  element: '#some-element',
  popover: {
    title: 'Important Feature',
    description: 'This is an important feature you should know about.'
  }
});

The highlight() method accepts the same step definition as tour steps but applies to one element only.

Without Element (Modal)

Omitting the element property displays the popover as a centered modal:

driverObj.highlight({
  popover: {
    title: 'Welcome',
    description: 'Welcome to our application!'
  }
});

Notes

• drive() starts the tour at step 0 by default; pass an index to start at a different step: drive(2)
• When using highlight(), only the close button is shown by default (no next/previous)
• The popover title and description both support HTML content

Related

• Configuration
• Methods

Installation

Driver.js is a lightweight (~5kb gzipped), no-dependency JavaScript library for creating powerful product tours, feature introductions, and element highlighting on web pages.

Package Manager

npm install driver.js
# or
yarn add driver.js
# or
pnpm add driver.js

Import

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

Both the JavaScript module and the CSS file must be imported. The CSS provides default styling for the popover and overlay.

CDN

<script src="https://cdn.jsdelivr.net/npm/driver.js@1/dist/driver.js.iife.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@1/dist/driver.css"/>

<script>
  const driverObj = window.driver.js.driver();
  driverObj.highlight({
    element: '#some-element',
    popover: {
      title: 'Title',
      description: 'Description'
    }
  });
</script>

When using the CDN version, the library is available via window.driver.js.driver.

Notes

• Driver.js works with vanilla JavaScript as well as any frontend framework (React, Vue, Angular, etc.)
• The CSS import is required for default popover and overlay styling
• TypeScript types are included in the package

Related

• Basic Usage

Driver.js — Getting Started

Migrate to 1.x

Guide for migrating from Driver.js 0.x to 1.x.

Import Changes

// 0.x
import Driver from 'driver.js';
import 'driver.js/dist/driver.min.css';

// 1.x
import { driver } from 'driver.js';
import 'driver.js/dist/driver.css';

The default export has been replaced with a named export. The CSS filename changed from driver.min.css to driver.css.

Initialization Changes

// 0.x
const driverObj = new Driver();
driverObj.defineSteps([/* steps */]);
driverObj.start();

// 1.x
const driverObj = driver({
  steps: [/* steps */]
});
driverObj.drive();

Steps are now passed directly to the driver() function instead of calling defineSteps() separately.

Renamed Options

Removed Options

New Options

Popover Position Changes

// 0.x
{ position: 'left-center' }

// 1.x
{ side: 'left', align: 'center' }

The single position string has been split into side and align properties. Element and title/description are now optional (enabling modal-style steps).

Callback Signature Changes

All callbacks now receive three parameters: (element, step, options) where options contains { config, state }.

Updated callbacks: onHighlightStarted, onHighlighted, onDeselected, onDestroyStarted, onDestroyed, onCloseClick, onNextClick, onPrevClick.

When overriding onNextClick or onPrevClick, you must manually call moveNext() or movePrevious(). The old preventMove() method is no longer needed — async flow control is now built-in.

Renamed API Methods

New API Methods

Related

• Configuration
• Methods

Driver.js — Migration