Checklist is a React component from VLLNT UI that renders a list of toggleable items with live progress tracking. It shows a completion bar, a checked count and percentage, and a message once all items are done.

How do I add Checklist?

Run `pnpm dlx shadcn@latest add https://ui.vllnt.com/r/checklist.json` to install Checklist via the shadcn CLI. The component source is copied into your project so you can adapt items, titles, and styling.

Does Checklist remember progress?

Yes. Provide a persistKey and the checked items are saved to localStorage under that key, so progress is restored on the next visit. Toggling also dispatches a progress-change event other components can listen for.

Checklist

Interactive checklist with progress tracking and toggleable items. Install Checklist from the VLLNT UI registry with the shadcn CLI.

Report a bug

What it is and when to use

Checklist is an interactive task list that tracks completion. Each item toggles between checked and unchecked, striking through completed labels and updating a progress bar with a count and percentage. Pass a persistKey to save progress to localStorage across visits, and an onComplete callback fires once every item is checked. Optional titles and per-item descriptions make it suited to onboarding flows, setup guides, and tutorial step tracking.

Learning

Interactive checklist with progress tracking and toggleable items. Part of the learning family in VLLNT UI, it ships as a machine-readable registry entry — copy the source directly into your app with the shadcn CLI and own it, no runtime dependency on a component library.

Preview

Switch between light and dark to inspect the embedded Storybook preview.

Installation

Add Checklist to your project with the shadcn CLI. The source lands in your codebase, ready to adapt:

pnpm dlx shadcn@latest add https://ui.vllnt.com/r/checklist.json

Source

"use client";

import { useState } from "react";

import type { HeadingTag } from "../../lib/types";
import { cn } from "../../lib/utils";

export const CHECKLIST_PROGRESS_EVENT = "vllnt:checklist-progress-change";
export const CHECKLIST_STORAGE_VERSION = 1;

export type ChecklistItem = {
  description?: string;
  id: string;
  label: string;
};

type ChecklistStoragePayload = {
  checked: string[];
  version: typeof CHECKLIST_STORAGE_VERSION;
};

function stringItemsFromUnknown(value: unknown): string[] {
  return Array.isArray(value)
    ? value.filter((item): item is string => typeof item === "string")
    : [];
}

export function parseChecklistStorageValue(saved: string): string[] {
  try {
    const parsed: unknown = JSON.parse(saved);

    if (Array.isArray(parsed)) {
      return stringItemsFromUnknown(parsed);
    }

    if (
      typeof parsed === "object" &&
      parsed !== null &&
      "version" in parsed &&
      "checked" in parsed &&
      parsed.version === CHECKLIST_STORAGE_VERSION
    ) {
      return stringItemsFromUnknown(parsed.checked);
    }
  } catch {
    return [];
  }

  return [];
}

export function createChecklistStorageValue(ids: Iterable<string>): string {
  const payload: ChecklistStoragePayload = {
    checked: [...ids],
    version: CHECKLIST_STORAGE_VERSION,
  };

  return JSON.stringify(payload);
}

type ChecklistItemRowProps = {
  isChecked: boolean;
  item: ChecklistItem;
  onToggle: () => void;
};

function ChecklistItemRow({
  isChecked,
  item,
  onToggle,
}: ChecklistItemRowProps): React.ReactNode {
  return (
    <li>
      <button
        className={cn(
          "w-full flex items-start gap-3 p-2 rounded-md text-left transition-colors hover:bg-muted/50",
          isChecked && "opacity-60",
        )}
        onClick={onToggle}
        type="button"
      >
        {isChecked ? (
          <svg
            className="size-5 text-green-500 flex-shrink-0 mt-0.5"
            fill="none"
            stroke="currentColor"
            viewBox="0 0 24 24"
          >
            <path
              d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"
              strokeLinecap="round"
              strokeLinejoin="round"
              strokeWidth={2}
            />
          </svg>
        ) : (
          <svg
            className="size-5 text-muted-foreground flex-shrink-0 mt-0.5"
            fill="none"
            stroke="currentColor"
            viewBox="0 0 24 24"
          >
            <rect
              height="18"
              rx="2"
              strokeLinecap="round"
              strokeLinejoin="round"
              strokeWidth={2}
              width="18"
              x="3"
              y="3"
            />
          </svg>
        )}
        <div className="flex-1 min-w-0">
          <span className={cn("text-sm", isChecked && "line-through")}>
            {item.label}
          </span>
          {item.description ? (
            <p className="text-xs text-muted-foreground mt-0.5">
              {item.description}
            </p>
          ) : null}
        </div>
      </button>
    </li>
  );
}

type ChecklistHeaderProps = {
  checked: number;
  Heading: HeadingTag;
  progress: number;
  title?: string;
  total: number;
};

function ChecklistHeader({
  checked,
  Heading,
  progress,
  title,
  total,
}: ChecklistHeaderProps): React.ReactNode {
  if (!title) return null;
  return (
    <div className="flex items-center justify-between mb-3">
      <Heading className="font-semibold flex items-center gap-2">
        <svg
          className="size-5 text-primary"
          fill="none"
          stroke="currentColor"
          viewBox="0 0 24 24"
        >
          <path
            d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"
            strokeLinecap="round"
            strokeLinejoin="round"
            strokeWidth={2}
          />
        </svg>
        {title}
      </Heading>
      <span className="text-xs text-muted-foreground">
        {checked}/{total} ({progress}%)
      </span>
    </div>
  );
}

export type ChecklistProps = {
  /** Heading tag for the checklist title. Defaults to `h4`. */
  as?: HeadingTag;
  className?: string;
  items: ChecklistItem[];
  onComplete?: () => void;
  persistKey?: string;
  title?: string;
};

// eslint-disable-next-line max-lines-per-function -- Complex interactive component with state and localStorage
export function Checklist({
  as: Heading = "h4",
  className,
  items,
  onComplete,
  persistKey,
  title,
}: ChecklistProps): React.ReactNode {
  const [checked, setChecked] = useState<Set<string>>(() => {
    if (typeof window !== "undefined" && persistKey) {
      const saved = localStorage.getItem(`checklist:${persistKey}`);
      if (saved) {
        return new Set(parseChecklistStorageValue(saved));
      }
    }
    return new Set();
  });

  const toggleItem = (id: string): void => {
    const newChecked = new Set(checked);
    if (newChecked.has(id)) newChecked.delete(id);
    else newChecked.add(id);
    setChecked(newChecked);
    if (persistKey) {
      try {
        localStorage.setItem(
          `checklist:${persistKey}`,
          createChecklistStorageValue(newChecked),
        );
        window.dispatchEvent(
          new CustomEvent(CHECKLIST_PROGRESS_EVENT, {
            detail: { persistKey },
          }),
        );
      } catch {
        /* skip */
      }
    }
    if (newChecked.size === items.length) {
      onComplete?.();
    }
  };

  const allChecked = checked.size === items.length;
  const progress =
    items.length > 0 ? Math.round((checked.size / items.length) * 100) : 0;

  return (
    <div className={cn("my-6 rounded-lg border bg-card p-4", className)}>
      <ChecklistHeader
        checked={checked.size}
        Heading={Heading}
        progress={progress}
        title={title}
        total={items.length}
      />
      <div className="h-1 bg-muted rounded-full mb-4 overflow-hidden">
        <div
          className={cn(
            "h-full transition-all duration-300",
            allChecked ? "bg-green-500" : "bg-primary",
          )}
          style={{ width: `${progress}%` }}
        />
      </div>
      <ul className="space-y-2">
        {items.map((item) => (
          <ChecklistItemRow
            isChecked={checked.has(item.id)}
            item={item}
            key={item.id}
            onToggle={() => {
              toggleItem(item.id);
            }}
          />
        ))}
      </ul>
      {allChecked ? (
        <div className="mt-4 p-2 rounded bg-green-500/10 text-green-700 dark:text-green-300 text-sm text-center">
          All items completed!
        </div>
      ) : null}
    </div>
  );
}

Stories

Explore every variant and state in the interactive Storybook:

Preview

Switch between light and dark to inspect the embedded Storybook preview.

Dependencies

@vllnt/ui@^0.3.0

FAQ

What is Checklist?: Checklist is a React component from VLLNT UI that renders a list of toggleable items with live progress tracking. It shows a completion bar, a checked count and percentage, and a message once all items are done.
How do I add Checklist?: Run `pnpm dlx shadcn@latest add https://ui.vllnt.com/r/checklist.json` to install Checklist via the shadcn CLI. The component source is copied into your project so you can adapt items, titles, and styling.
Does Checklist remember progress?: Yes. Provide a persistKey and the checked items are saved to localStorage under that key, so progress is restored on the next visit. Toggling also dispatches a progress-change event other components can listen for.

Share this component

Share on X Share on LinkedIn Share on Facebook Share on Mastodon Share on Bluesky Share on Threads