Types

TypeScript types for ChecklistConfig, TaskConfig, TaskDependency, ChecklistState, and the full checklists type system

TypeScript type definitions exported by @tour-kit/checklists.

Core Types

ChecklistConfig

Checklist configuration:

interface ChecklistConfig {
  id: string;
  title: string;
  description?: string;
  icon?: string | ReactNode;
  tasks: ChecklistTaskConfig[];
  onComplete?: () => void;
  onDismiss?: () => void;
  dismissible?: boolean;
  hideOnComplete?: boolean;
  meta?: Record<string, unknown>;
}

ChecklistTaskConfig

Task configuration:

interface ChecklistTaskConfig {
  id: string;
  title: string;
  description?: string;
  icon?: string | ReactNode;
  action?: TaskAction;
  dependsOn?: string[];
  when?: (context: ChecklistContext) => boolean;
  completedWhen?: TaskCompletionCondition;
  manualComplete?: boolean;
  meta?: Record<string, unknown>;
}

State Types

ChecklistState

Runtime checklist state:

interface ChecklistState {
  config: ChecklistConfig;
  tasks: ChecklistTaskState[];
  progress: number;
  completedCount: number;
  totalCount: number;
  isComplete: boolean;
  isDismissed: boolean;
  isExpanded: boolean;
}

ChecklistTaskState

Runtime task state:

interface ChecklistTaskState {
  config: ChecklistTaskConfig;
  completed: boolean;
  locked: boolean;
  visible: boolean;
  active: boolean;
  completedAt?: number;
}

Action Types

TaskAction

Actions that can be triggered:

type TaskAction =
  | { type: 'navigate'; url: string; external?: boolean }
  | { type: 'callback'; handler: () => void | Promise<void> }
  | { type: 'tour'; tourId: string }
  | { type: 'modal'; modalId: string }
  | { type: 'custom'; data: unknown };

TaskCompletionCondition

Auto-completion conditions:

type TaskCompletionCondition =
  | { tourCompleted: string }
  | { tourStarted: string }
  | { custom: (context: ChecklistContext) => boolean };

Context Types

ChecklistContext

Context available to conditions:

interface ChecklistContext {
  user: Record<string, unknown>;
  data: Record<string, unknown>;
  completedTasks: string[];
  completedTours: string[];
}

Progress Types

ChecklistProgress

Progress information:

interface ChecklistProgress {
  completed: number;
  total: number;
  percentage: number;
  remaining: number;
}

Config Types

ChecklistProviderConfig

Provider configuration:

interface ChecklistProviderConfig {
  checklists: ChecklistConfig[];
  persistence?: ChecklistPersistenceConfig;
  context?: {
    user?: Record<string, unknown>;
    data?: Record<string, unknown>;
  };
  onTaskComplete?: (checklistId: string, taskId: string) => void;
  onTaskUncomplete?: (checklistId: string, taskId: string) => void;
  onChecklistComplete?: (checklistId: string) => void;
  onChecklistDismiss?: (checklistId: string) => void;
  onTaskAction?: (checklistId: string, taskId: string, action: TaskAction) => void;
}

ChecklistPersistenceConfig

Persistence configuration:

interface ChecklistPersistenceConfig {
  enabled: boolean;
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
  key?: string;
  onSave?: (state: PersistedChecklistState) => void;
  onLoad?: () => PersistedChecklistState | null | Promise<PersistedChecklistState | null>;
}

PersistedChecklistState

Persisted state format:

interface PersistedChecklistState {
  completed: Record<string, string[]>;
  dismissed: string[];
  timestamp: number;
}

Hook Return Types

UseChecklistReturn

Returned by useChecklist:

interface UseChecklistReturn {
  checklist: ChecklistState | undefined;
  tasks: ChecklistTaskState[];
  visibleTasks: ChecklistTaskState[];
  progress: ChecklistProgress;
  exists: boolean;
  isComplete: boolean;
  isDismissed: boolean;
  isExpanded: boolean;
  completeTask: (taskId: string) => void;
  uncompleteTask: (taskId: string) => void;
  executeAction: (taskId: string) => void;
  dismiss: () => void;
  restore: () => void;
  toggleExpanded: () => void;
  setExpanded: (expanded: boolean) => void;
  reset: () => void;
}

UseTaskReturn

Returned by useTask:

interface UseTaskReturn {
  task: ChecklistTaskState | undefined;
  exists: boolean;
  isCompleted: boolean;
  isLocked: boolean;
  isVisible: boolean;
  complete: () => void;
  uncomplete: () => void;
  execute: () => void;
  toggle: () => void;
}

Import Paths

import type {
  // Configs
  ChecklistConfig,
  ChecklistTaskConfig,
  ChecklistProviderConfig,
  ChecklistPersistenceConfig,

  // States
  ChecklistState,
  ChecklistTaskState,
  PersistedChecklistState,

  // Actions & Conditions
  TaskAction,
  TaskCompletionCondition,

  // Context & Progress
  ChecklistContext,
  ChecklistProgress,

  // Hook Returns
  UseChecklistReturn,
  UseTaskReturn,
} from '@tour-kit/checklists';

Component Props

ChecklistProps

interface ChecklistProps
  extends React.ComponentPropsWithoutRef<'div'>,
    ChecklistVariants {
  checklistId: string
  showHeader?: boolean
  showProgress?: boolean
  showDismiss?: boolean
  asChild?: boolean
  renderTask?: (task, actions: { execute(): void; toggle(): void }) => React.ReactNode
}

ChecklistTaskProps

interface ChecklistTaskProps
  extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onClick'>,
    Omit<ChecklistTaskVariants, 'state'> {
  task: ChecklistTaskState
  onClick?: () => void
  onToggle?: () => void
  renderIcon?: (task: ChecklistTaskState) => React.ReactNode
}

ChecklistProgressProps

interface ChecklistProgressProps
  extends React.ComponentPropsWithoutRef<'div'>,
    ChecklistProgressVariants,
    ProgressBarVariants {
  value: number
  max: number
  showPercentage?: boolean
  showCount?: boolean
  trackClassName?: string
  barClassName?: string
}

ChecklistLauncherProps

interface ChecklistLauncherProps
  extends Omit<React.ComponentPropsWithoutRef<'button'>, 'children'>,
    ChecklistLauncherVariants,
    LauncherPositionVariants {
  checklistId: string
  badgeVariant?: LauncherBadgeVariants['variant']
  panelClassName?: string
  children?: React.ReactNode
}

ChecklistPanelProps

interface ChecklistPanelProps
  extends React.ComponentPropsWithoutRef<'div'>,
    ChecklistPanelVariants {
  checklistId: string
  defaultExpanded?: boolean
  collapsible?: boolean
  asChild?: boolean
}

Headless Component Props

ChecklistHeadlessProps

interface ChecklistHeadlessProps {
  checklistId: string
  render: (props: ChecklistRenderProps) => React.ReactNode
  children?: (props: ChecklistRenderProps) => React.ReactNode
}

TaskHeadlessProps

interface TaskHeadlessProps {
  checklistId: string
  taskId: string
  render: (props: TaskRenderProps) => React.ReactNode
  children?: (props: TaskRenderProps) => React.ReactNode
}

Context Types

ChecklistContextValue

interface ChecklistContextValue {
  checklists: Map<string, ChecklistState>
  context: ChecklistContext
  getChecklist(id: string): ChecklistState | undefined
  completeTask(checklistId: string, taskId: string): void
  uncompleteTask(checklistId: string, taskId: string): void
  executeAction(checklistId: string, taskId: string): void
  dismissChecklist(checklistId: string): void
  restoreChecklist(checklistId: string): void
  toggleExpanded(checklistId: string): void
  setExpanded(checklistId: string, expanded: boolean): void
  resetChecklist(checklistId: string): void
  resetAll(): void
  getProgress(checklistId: string): ChecklistProgress
}

Alias for the user-context object passed via <ChecklistProvider context={...}>. Used for evaluating per-task when() conditions. Renamed in the public surface so it doesn't collide with the React ChecklistContext value.

import type { ChecklistContextData } from '@tour-kit/checklists'

ChecklistProgressType

Alias for ChecklistProgress exposed via the public surface (avoids name collision with the <ChecklistProgress> component).

import type { ChecklistProgressType } from '@tour-kit/checklists'

Hook Return Types

UseChecklistPersistenceReturn

interface UseChecklistPersistenceReturn {
  save: (state: PersistedChecklistState) => void
  load: () => PersistedChecklistState | Promise<PersistedChecklistState | null> | null
  clear: () => void
}

Variants Types

CVA-derived variant prop types. Each pairs with a same-named lowercase function — see Variants.

Type	Variant fn	Slots
`ChecklistVariants`	`checklistVariants`	`size`
`ChecklistHeaderVariants`	`checklistHeaderVariants`	`spacing`
`ChecklistContentVariants`	`checklistContentVariants`	`spacing`
`ChecklistCompleteVariants`	`checklistCompleteVariants`	`variant`
`ChecklistTaskVariants`	`checklistTaskVariants`	`size`, `state`
`TaskCheckboxVariants`	`taskCheckboxVariants`	`size`, `state`
`TaskTitleVariants`	`taskTitleVariants`	`size`, `state`
`TaskDescriptionVariants`	`taskDescriptionVariants`	`size`
`ChecklistProgressVariants`	`checklistProgressVariants`	`size`
`ProgressBarVariants`	`progressBarVariants`	`variant`
`ProgressTrackVariants`	`progressTrackVariants`	`size`
`ProgressTextVariants`	`progressTextVariants`	`size`
`ChecklistLauncherVariants`	`checklistLauncherVariants`	`size`, `variant`
`LauncherBadgeVariants`	`launcherBadgeVariants`	`size`, `variant`
`LauncherPositionVariants`	`launcherPositionVariants`	`position`
`ChecklistPanelVariants`	`checklistPanelVariants`	`size`
`PanelHeaderVariants`	`panelHeaderVariants`	`spacing`, `collapsible`
`PanelContentVariants`	`panelContentVariants`	`expanded`
`PanelChevronVariants`	`panelChevronVariants`	`size`, `expanded`

Cross-Cutting

Type	Notes
`UILibrary`	`'radix-ui' \| 'base-ui'` — see Unified Slot

ChecklistProvider - Provider usage
Hooks - Hook usage
Variants - Styling reference

Types

On this page