Onboarding checklists that stay out of your way

The package is ESM only. With a bundler, just import it. Without one, map the package name in an import map and serve the page over HTTP. ES modules don’t load from file://.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Checklist</title>
    <script type="importmap">
      {
        "imports": {
          "@stepr/checklist": "/node_modules/@stepr/checklist/dist/index.js"
        }
      }
    </script>
  </head>
  <body>
    <div id="onboarding"></div>
    <script type="module">
      import { createChecklist } from '@stepr/checklist';

      createChecklist({
        container: '#onboarding',
        title: 'Get started',
        steps: [
          {
            id: 'profile',
            label: 'Complete your profile',
            onClick: (step, checklist) => checklist.complete(step.id),
          },
          { id: 'docs', label: 'Read the docs' },
        ],
      });
    </script>
  </body>
</html>

Activating a step only calls its onClick. Mark a step done when the work actually happens, from any code that holds the checklist. Steps without onClick are rendered as text.

import { createChecklist } from '@stepr/checklist';

const checklist = createChecklist({
  container: '#onboarding',
  title: 'Get started',
  steps: [
    {
      id: 'profile',
      label: 'Complete your profile',
      onClick: () => openProfileForm(), // opening the form does not complete it
    },
    { id: 'verify', label: 'Verify your email address' }, // text only
  ],
  onChange: ({ progress }) => {
    if (progress.completed === progress.total) showAllDoneMessage();
  },
});

// Complete steps when the work is actually done, from anywhere in your app:
onProfileSaved(() => checklist.complete('profile'));
onEmailVerified(() => checklist.complete('verify'));

Persistence is opt-in. Completed step ids are stored in localStorage under your key. If storage is unavailable or full, the checklist keeps working in memory.

import { createChecklist } from '@stepr/checklist';

const checklist = createChecklist({
  container: '#onboarding',
  title: 'Get started',
  steps: [
    { id: 'profile', label: 'Complete your profile' },
    { id: 'invite', label: 'Invite a teammate' },
  ],
  storageKey: 'my-app:onboarding', // restored on creation, saved on change
});

checklist.complete('invite'); // true, and saved
checklist.complete('invite'); // false: already complete, nothing saved
checklist.getProgress(); // { completed: 1, total: 2 }

checklist.reset(); // marks every step incomplete, and saves that
checklist.destroy(); // removes the widget; saved progress is kept
localStorage.removeItem('my-app:onboarding'); // forget saved progress

The checklist doesn’t know about tours. Your app connects the two libraries with callbacks: the step’s onClick starts the tour, and the tour’s onComplete completes the step. Closing the tour early leaves the step open. Stepr is a separate package that you install yourself.

import { createChecklist } from '@stepr/checklist';
import { createTour } from 'stepr';

const tour = createTour({
  steps: [
    { target: '#new-project', title: 'Projects', description: 'Start here.' },
    { target: '#invite', title: 'Invite your team' },
  ],
  onComplete: () => checklist.complete('tour'), // finished: tick it off
  onExit: () => {}, // closed early: the step stays incomplete
});

const checklist = createChecklist({
  container: '#onboarding',
  title: 'Get started',
  steps: [
    {
      id: 'tour',
      label: 'Take the product tour',
      onClick: () => {
        if (!tour.start()) console.warn('No tour target is visible');
      },
    },
  ],
});

Set the properties on the widget or on any ancestor, such as the container. This is the demo’s “Violet” theme. If you change colors, check the contrast yourself.

/* <div id="onboarding" class="theme-violet"></div> */
.theme-violet {
  --stepr-checklist-accent: #6d28d9;
  --stepr-checklist-focus: #6d28d9;
  --stepr-checklist-background: #faf5ff;
  --stepr-checklist-hover: #f3e8ff;
  --stepr-checklist-border: #8b5cf6;
  --stepr-checklist-radius: 1rem;
}