# API Reference

> Complete Driver.js API reference: every method available on the driver, hints and checklist instances, with examples.

`driver()` returns an object with the methods below. The options it takes are in [Configuration](https://driverjs.com/docs/configuration.md).

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

const driverObj = driver({
  steps: [
    { element: "#search", popover: { title: "Search" } },
    { element: "#export", popover: { title: "Export" } },
  ],
});
```

## Starting and Stopping

```js
driverObj.drive(); // Start the tour at the first step
driverObj.drive(2); // Start at the third step

// Show one step on its own, without a tour
driverObj.highlight({
  element: "#search",
  popover: { title: "Search", description: "Find anything." },
});

driverObj.destroy(); // End the tour or highlight
driverObj.isActive(); // true while a tour or highlight is showing
```

`destroy()` doesn't run `onDestroyStarted`, so you can call it from that hook. The other destroy hooks get the [reason](https://driverjs.com/docs/configuration.md#why-a-tour-ended) `"api"`, or the reason of the user action when you call it from a hook.

## Navigation

```js
driverObj.moveNext(); // Go to the next step. Ends the tour on the last one
driverObj.movePrevious(); // Go to the previous step
driverObj.moveTo(3); // Go to the step with this index
driverObj.advance(); // Complete the current step
```

`advance()` completes the step the way [`advanceOn`](https://driverjs.com/docs/configuration.md#advanceon) does: it waits for `advanceDelay`, then runs `onNextClick` or moves on. Use it when your app decides the step is done, like after a save. `moveNext()` moves right away and doesn't run `onNextClick`.

```js
{
  element: "#save",
  advanceDelay: 600,
  onHighlighted: (element, step, { signal, driver }) => {
    window.addEventListener("profile-saved", () => driver.advance(), {
      signal,
    });
  },
  popover: {
    title: "Save your profile",
    instruction: "Click <b>Save</b>.",
  },
}
```

`movePrevious()` on the first step and `moveTo()` with an index that doesn't exist end the tour. `moveTo()` also starts the tour when it isn't running, like `drive()`. `moveNext()` and `movePrevious()` do nothing then.

## The Current Step

```js
driverObj.getActiveIndex(); // Active step index, undefined in highlight()
driverObj.getActiveStep(); // The active step
driverObj.getActiveElement(); // The highlighted element

driverObj.getPreviousStep(); // The step that was active before this one
driverObj.getPreviousElement(); // And its element
driverObj.getNextStep(); // The step moveNext() would show

driverObj.isFirstStep(); // No step to go back to
driverObj.isLastStep(); // No step to go on to
driverObj.hasNextStep();
driverObj.hasPreviousStep();
```

These account for steps that [`skipMissingElement`](https://driverjs.com/docs/configuration.md#missing-elements) would skip. `isFirstStep()` and `isLastStep()` return `false` when no tour is running.

## Changing the Popover

```js
// Change the visible popover. Changes merge, and last until the step
// is left.
driverObj.updatePopover({ description: "Almost there." });
driverObj.updatePopover({
  nextBtnText: "Continue",
  disableButtons: ["previous"],
});

// Restore the step's own popover
driverObj.updatePopover();
```

`updatePopover()` takes `title`, `description`, `instruction`, `showButtons`, `disableButtons`, `showProgress`, `progressText`, `nextBtnText`, `prevBtnText`, `closeBtnLabel` and `popoverClass`. Changed text is announced to screen readers. It can change the text of an [action step](https://driverjs.com/docs/configuration.md#action-steps), but not turn a step into one.

```js
// Shake the popover to draw attention to it
driverObj.nudge();

// Shake it and show a line of feedback under the instruction.
// The line goes away with the next nudge() or step.
driverObj.nudge("Not that one. Click <b>Inbox</b>.");

// Shake it and change the popover like updatePopover() does
driverObj.nudge({ description: "Not quite. Choose Editor." });
```

```js
// Redraw the highlight and popover after a layout change.
// Resizes, scrolling and size changes of the element are followed already.
driverObj.refresh();
```

## Configuration

```js
driverObj.getConfig(); // The current configuration
driverObj.getState(); // The current state, see Configuration
driverObj.getState("activeIndex"); // One key of it

// Replace the steps
driverObj.setSteps([
  { element: "#billing", popover: { title: "Billing" } },
]);

// Replace the configuration
driverObj.setConfig({ ...driverObj.getConfig(), showProgress: true });
```

`setConfig()` replaces the whole configuration, including `steps`. Spread `getConfig()` to keep what you had. After `setSteps()` on a running tour, call `drive()` to show the new steps.

## Types

```ts
import type {
  Config,
  DriveStep,
  Popover,
  Driver,
  State,
  PopoverDOM,
  PopoverPatch,
  DriverHook,
  HookOpts,
  DestroyReason,
  AdvanceOn,
  AdvanceOnEvent,
  AllowedElements,
  InteractionHook,
  ElementMissing,
  ElementMissingHook,
  Side,
  Alignment,
  AllowedButtons,
} from "driver.js";
```

## Hints

`hints()` returns its own object. Options are in [Hints Configuration](https://driverjs.com/docs/configuration.md#hints-configuration), examples in the [Hints guide](https://driverjs.com/docs/hints.md).

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

const productHints = hints({
  hints: [
    { element: "#export", id: "export", popover: { title: "Export" } },
  ],
});

// Show the beacons. Call again to pick up elements that appeared since
productHints.show();
productHints.hide(); // Remove the beacons
productHints.isVisible();

// By id, or by index when the hint has no id
productHints.open("export"); // Open a hint's popover
productHints.close(); // Close the open popover, keeping its beacon
productHints.dismiss("export"); // Remove a hint's beacon and run onDismiss
productHints.restore("export"); // Bring a dismissed hint back
productHints.restoreAll();

productHints.getHints(); // The configured hints
productHints.getActive(); // The hint whose popover is open, if any
productHints.setHints([]); // Replace the hints. Dismissals are forgotten

productHints.refresh(); // Reposition after a layout change
```

## Checklists

`checklist()` returns its own object. Options are in [Checklist Configuration](https://driverjs.com/docs/configuration.md#checklist-configuration), examples in the [Checklists guide](https://driverjs.com/docs/checklists.md).

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

const onboarding = checklist({
  id: "onboarding",
  items: [
    {
      id: "tour",
      title: "Take the tour",
      tour: [{ element: "#search", popover: { title: "Search" } }],
    },
    { id: "github", title: "Connect GitHub" },
  ],
});

onboarding.show(); // Add the widget to the page
onboarding.hide(); // Remove it
onboarding.isVisible();

onboarding.open(); // Open the panel
onboarding.close(); // Close the panel, keeping the launcher
onboarding.toggle();
onboarding.isOpen();

onboarding.start("tour"); // Run an item's tour, link or action
onboarding.complete("github"); // Tick an item
onboarding.uncomplete("github"); // Untick it
onboarding.reset(); // Untick every item
onboarding.refresh(); // Check every item's completeWhen again

onboarding.getProgress(); // { completed: ["github"], done: 1, total: 2 }
onboarding.getItems(); // The configured items
```
