Checklists

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:

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.

Dashboard
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, 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().

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.

Dashboard
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.

Tick an item, reload the page, and open the checklist again. The ticks are still there.

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.

Dashboard
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:

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.

Website redesign
  1. Events show up here.

The event types are shown, hidden, opened, closed, item_started, item_completed, item_uncompleted, tour_ended (with the tour’s reason), 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:

Dashboard
checklist({
  id: "onboarding",
  className: "checklist-brutalist",
  items,
});
  • Checklist Themes has its CSS and more themes to copy.
  • Theming 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".

Dashboard

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

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}}.

Dashboard
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:

Dashboard
Set up the checklist first.

Reference