# Checklists

> Add an onboarding checklist to your app with Driver.js. Items launch product tours, follow links or wait for the user to do something, and tick themselves off as users make progress.

A checklist is a "Get started" widget in the corner of your app. Each item is one thing you want new users to do. An item can start a tour, open a link or run your code, and it ticks itself off once the user has done it.

Checklists are a separate entry. Their items run tours, so import `driver.css` as well:

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

Finish the tour below to tick its item. Close it early and the item stays open. _Connect GitHub_ in the mock dashboard ticks the second item.

```js
const onboarding = checklist({
  id: "onboarding",
  title: "Get started",
  description: "Four steps to your first project.",
  items: [
    {
      id: "tour",
      title: "Take the tour",
      tour: [
        {
          element: "#new-project",
          popover: { title: "New Project", description: "..." },
        },
        {
          element: "#connect-github",
          popover: { title: "Connect GitHub", description: "..." },
        },
      ],
    },
    {
      id: "github",
      title: "Connect GitHub",
      completeWhen: () => user.githubConnected,
    },
    {
      id: "invite",
      title: "Invite a teammate",
      action: () => openInviteModal(),
    },
    {
      id: "docs",
      title: "Read about saving progress",
      href: "/docs/checklists#saving-progress",
    },
  ],
});

onboarding.show();
```

## Items

Every item needs an `id`. Saved progress is a list of these ids, so keep them the same when you reword or reorder items. Missing and duplicate ids log a warning.

What a click on an item does depends on what it has:

- `tour`: the checklist closes and the tour starts. The item is ticked only
  when the user finishes the tour; closing it early leaves the item open. The
  checklist opens again when the tour ends either way. Pass an array of steps,
  a full [driver configuration](https://driverjs.com/docs/configuration.md#driver-configuration), or
  a `driver()` instance you created yourself; its own hooks keep working.
- `href`: rendered as a link. The item is ticked on click and the link
  navigates as usual.
- `action`: your function runs with `(item, { checklist })` and the item is
  ticked.
- None of these: the item is a plain row, ticked by `completeWhen` or by
  calling `complete(id)`.

### Completing items from your app

For tasks done in your app, give the item a `completeWhen` function. The checklist ticks the item once it returns `true`. It is checked on `show()`, after the item's tour or action, and when you call `refresh()`.

```js
const onboarding = checklist({
  id: "onboarding",
  items: [
    {
      id: "github",
      title: "Connect GitHub",
      completeWhen: () => user.githubConnected,
    },
  ],
});

// After the user connects GitHub somewhere in your app
onboarding.refresh();
```

On an item with a tour, link or action, `completeWhen` replaces the default: the item is ticked only when it returns `true`. To tick an item yourself, call `onboarding.complete("github")`.

### Letting users tick items off

Some tasks can't be detected, like "Watch the intro video". With `allowManualComplete` the check circle becomes a button, and users tick or untick items themselves. A click on the item's text still runs its tour, link or action.

```js
checklist({
  id: "onboarding",
  allowManualComplete: true,
  items: [
    { id: "video", title: "Watch the intro video", href: "/intro" },
    // Only ticked by finishing the tour, even with manual completion on.
    {
      id: "tour",
      title: "Take the tour",
      tour: steps,
      allowManualComplete: false,
    },
  ],
});
```

An item's own `allowManualComplete` wins. From code, use `complete(id)` and `uncomplete(id)`.

## Saving progress

The checklist stores nothing. Pass the ids that are already done as `completed`, and save them in `onProgress`, which runs on every change. Keep them in localStorage, your API or the user record.

```js
const onboarding = checklist({
  id: "onboarding",
  items,
  completed: JSON.parse(localStorage.getItem("onboarding") ?? "[]"),
  onProgress: ({ completed, done, total }) => {
    localStorage.setItem("onboarding", JSON.stringify(completed));
  },
});

onboarding.show();
```

## When everything is done

Once every item is done, the checklist can show a different title, description and launcher text. The demo starts with three of four items done, so click the last one.

```js
checklist({
  id: "onboarding",
  completeTitle: "You're all set! 🎉",
  completeDescription: "Nice work. You're ready to go.",
  completeLauncherText: "All done",
  items,
});
```

The checklist stays on the page when it is done. To hide it, call `hide()` from `onComplete`. On later visits, check the saved progress before showing it:

```js
const onboarding = checklist({
  id: "onboarding",
  items,
  completed: savedProgress,
  onComplete: () => setTimeout(() => onboarding.hide(), 3000),
});

const { done, total } = onboarding.getProgress();
if (done < total) {
  onboarding.show();
}
```

## Tracking events

`onEvent` gets everything that happens in the checklist, ready to send to your analytics. Open the checklist below, take the tour, and watch the events.

```js
checklist({
  id: "onboarding",
  items,
  onEvent: event => {
    // { kind: "checklist", id: "onboarding", type: "item_completed",
    //   itemId: "github", timestamp: 1760000000000 }
    analytics.track(`checklist_${event.type}`, event);
  },
});
```

The event types are `shown`, `hidden`, `opened`, `closed`, `item_started`,
`item_completed`, `item_uncompleted`, `tour_ended` (with the tour's [`reason`](https://driverjs.com/docs/configuration.md#why-a-tour-ended)),
`completed` and `reset`.

## Customizing

### Theme

Pass `className` to put your own class on the widget, then style its parts. This is the theme of the driver.js homepage:

```js
checklist({
  id: "onboarding",
  className: "checklist-brutalist",
  items,
});
```

- [Checklist Themes](https://driverjs.com/docs/checklist-themes.md) has its CSS and more themes to copy.
- [Theming](https://driverjs.com/docs/theming.md#checklist) has the accent color variable and every class name.

### Position

`position` moves the widget to a corner: `"bottom-right"` (default), `"bottom-left"`, `"top-right"` or `"top-left"`.

`offset` sets the distance from the screen edges in pixels, for example to make room for a chat bubble:

```js
checklist({
  id: "onboarding",
  position: "bottom-right",
  offset: { x: 20, y: 90 },
  items,
});
```

The default is 20 pixels, or 12 on screens narrower than 480 pixels, where the panel also spans the width of the screen.

### Text

Every text of the widget can be changed. `progressText` and `launcherProgressText` replace `{{done}}`, `{{total}}`, `{{remaining}}` and `{{percent}}`.

```js
checklist({
  id: "onboarding",
  title: "Welcome aboard 👋",
  description: "Finish these to unlock your workspace.",
  launcherText: "Setup guide",
  progressText: "{{done}}/{{total}} complete",
  launcherProgressText: "{{done}} of {{total}}",
  items,
});
```

### Your Own Launcher

`launcher: false` hides the floating button. Open the panel from your own button:

```js
const onboarding = checklist({ id: "onboarding", launcher: false, items });

onboarding.show();
document
  .querySelector("#help-button")
  .addEventListener("click", () => onboarding.toggle());
```

## Reference

- Every option: [Checklist Configuration](https://driverjs.com/docs/configuration.md#checklist-configuration)
- Every method: [API Reference](https://driverjs.com/docs/api.md#checklists)
