Checklists

Checklists are onboarding task lists that help users complete a set of actions to get started with your product. They display as a floating panel with checkable items, a progress bar, and optional rewards for completion.

Overview

A checklist consists of:

Launcher -- A floating button or badge that opens the checklist panel
Panel -- A slide-out or dropdown panel listing all checklist items
Items -- Individual tasks with titles, descriptions, and completion criteria
Progress bar -- Visual indicator showing how many items are complete
Completion state -- Celebration or reward when all items are done

Checklists are ideal for:

New user onboarding (complete your profile, invite a team member, create your first project)
Feature adoption campaigns (try 5 key features in your first week)
Setup wizards (connect data source, configure settings, verify integration)
Trial-to-paid conversion flows (complete these steps to get the most out of your trial)

Creating a Checklist

Via the Admin Panel

Navigate to Content > Checklists and click Create Checklist.
Enter a checklist title and optional description.
Add items, each with a title, description, and completion criteria.
Configure the launcher position and style.
Set trigger, audience, and scheduling rules.
Click Publish.

Via the API

All non-tour content shares one admin endpoint — POST /v1/admin/content — discriminated by content_type. The items / completion / cta structure below is rendered by the SDK at display time, not enforced by the API schema today.

bash

POST /v1/admin/content
Content-Type: application/json
X-Api-Key: sk_live_...

{
  "content_type": "checklist",
  "name": "Getting Started",
  "title": "Get Started with Acme",
  "description": "Complete these steps to set up your workspace.",
  "items": [
    {
      "item_id": "complete-profile",
      "title": "Complete Your Profile",
      "description": "Add your name and profile photo.",
      "completion": {
        "type": "url_visit",
        "url_pattern": "/settings/profile"
      },
      "cta": {
        "text": "Go to Profile",
        "action": "url",
        "url": "/settings/profile"
      }
    },
    {
      "item_id": "invite-team",
      "title": "Invite a Team Member",
      "description": "Collaboration works best with your team.",
      "completion": {
        "type": "event",
        "event_name": "team.member_invited"
      },
      "cta": {
        "text": "Invite Someone",
        "action": "url",
        "url": "/settings/team"
      }
    },
    {
      "item_id": "create-project",
      "title": "Create Your First Project",
      "description": "Projects organise your work into focused areas.",
      "completion": {
        "type": "event",
        "event_name": "project.created"
      },
      "cta": {
        "text": "New Project",
        "action": "url",
        "url": "/projects/new"
      }
    },
    {
      "item_id": "connect-data",
      "title": "Connect a Data Source",
      "description": "Import your data to start building dashboards.",
      "completion": {
        "type": "event",
        "event_name": "datasource.connected"
      },
      "cta": {
        "text": "Add Data Source",
        "action": "url",
        "url": "/integrations"
      }
    }
  ],
  "launcher": {
    "position": "bottom-right",
    "style": "badge",
    "label": "Getting Started"
  },
  "completion": {
    "title": "You're All Set!",
    "body": "You've completed all the setup steps. Time to explore.",
    "confetti": true
  },
  "trigger": {
    "trigger_type": "first_visit"
  },
  "audience": {
    "rules": [
      { "attribute": "signup_date", "operator": "gte", "values": ["2025-06-01"] }
    ]
  }
}

Configuration

Field	Type	Required	Description
`name`	`string`	Yes	Internal name for the checklist
`title`	`string`	Yes	Checklist heading shown to users
`description`	`string`	No	Subheading or introductory text
`items`	`array`	Yes	List of checklist items (see below)
`launcher`	`object`	No	Launcher button configuration
`completion`	`object`	No	Completion celebration configuration
`allow_skip`	`boolean`	No	Allow users to skip individual items (default: `false`)
`dismiss_on_complete`	`boolean`	No	Auto-dismiss the checklist when all items are done (default: `false`)
`trigger`	`object`	No	When to show the checklist
`audience`	`object`	No	Who should see the checklist

Checklist Items

Each item represents a single task for the user to complete:

Field	Type	Required	Description
`item_id`	`string`	Yes	Unique identifier for the item
`title`	`string`	Yes	Item title shown in the checklist
`description`	`string`	No	Brief description of what to do
`completion`	`object`	Yes	How the item is marked complete
`cta`	`object`	No	Action button for the item
`required`	`boolean`	No	Whether this item is required for checklist completion (default: `true`)

Completion Criteria

Each item has a completion condition that determines when it gets checked off:

Manual ClickCustom EventURL VisitTour Completion

json

{
  "completion": {
    "type": "manual"
  }
}

json

{
  "completion": {
    "type": "event",
    "event_name": "project.created"
  }
}

json

{
  "completion": {
    "type": "url_visit",
    "url_pattern": "/settings/profile"
  }
}

json

{
  "completion": {
    "type": "tour_complete",
    "tour_id": "dashboard-tour"
  }
}

Completion Type	Description
`manual`	User clicks the checkbox to mark it complete
`event`	Automatically completes when a matching event fires
`url_visit`	Automatically completes when the user visits a matching URL
`tour_complete`	Automatically completes when the user finishes a specific tour

TIP

URL-based completion confirms a page visit but not the action. Use event completion when you need precision (e.g. the user genuinely created a project, not just visited the page where they could).

Item CTA

Each item can have a call-to-action button that directs the user to complete the task:

json

{
  "cta": {
    "text": "Go to Settings",
    "action": "url",
    "url": "/settings/profile"
  }
}

CTA actions:

Action	Description
`url`	Navigate to a URL
`tour`	Start a specific tour
`track`	Fire a custom event

Launcher

The launcher is a floating button that opens the checklist panel. It persists on screen while the checklist has incomplete items.

Position

Value	Description
`bottom-right`	Bottom-right corner of the viewport (default)
`bottom-left`	Bottom-left corner of the viewport
`top-right`	Top-right corner of the viewport
`top-left`	Top-left corner of the viewport

Style

Style	Description
`badge`	Small badge showing the checklist label and progress count (default)
`button`	Prominent button with the checklist title
`icon`	Compact icon-only launcher

json

{
  "launcher": {
    "position": "bottom-right",
    "style": "badge",
    "label": "Setup Guide"
  }
}

The launcher displays a progress indicator (e.g., "2/4") showing how many items are complete.

Progress Tracking

Checklist progress is tracked per user. Each item's completion state is persisted, so if a user closes the browser and returns later, their progress is preserved.

The progress bar at the top of the checklist panel shows overall completion:

[===========--------] 3 of 5 complete

Progress bar styling uses the --spot-progress-bg and --spot-progress-fill theme variables.

Completion Celebration

When all required items are complete, the checklist can show a celebration:

json

{
  "completion": {
    "title": "Setup Complete!",
    "body": "You've finished all the setup steps. Explore your new workspace.",
    "confetti": true,
    "cta": {
      "text": "Start Exploring",
      "action": "url",
      "url": "/dashboard"
    }
  }
}

Field	Type	Description
`title`	`string`	Completion heading
`body`	`string`	Completion message (supports safe HTML)
`confetti`	`boolean`	Show a confetti animation on completion
`cta`	`object`	Optional action button

Skippable Items

When allow_skip is true, each item shows a "Skip" link that marks it as skipped. Skipped items count towards completion (the checklist can still reach 100%) but are tracked separately in analytics.

json

{
  "allow_skip": true
}

Items with required: true cannot be skipped even when allow_skip is enabled.

Programmatic Control

Checklists surface based on trigger + audience rules. Items complete via the configured completion type — url_visit, tour_complete, event, or manual (user clicks the checkbox).

Hook content:dismiss to react when a user closes the checklist:

Spotlight.on('content:dismiss', (data) => {
  console.log(`User dismissed content: ${data.contentId}`);
});

Styling

Checklists inherit all --spot-* theme variables. Key variables for checklist appearance:

Variable	Effect
`--spot-bg`	Panel background colour
`--spot-text`	Item text colour
`--spot-primary`	Launcher colour, checked item icon colour
`--spot-border`	Panel border, item divider colour
`--spot-radius-lg`	Panel border radius
`--spot-shadow-lg`	Panel box shadow
`--spot-progress-bg`	Progress bar background
`--spot-progress-fill`	Progress bar fill colour
`--spot-success`	Completed item checkmark colour

Analytics

Checklist analytics are tracked automatically:

Event	Description
`content:view`	Checklist panel was opened
`checklist:item_complete`	A single item was completed
`checklist:complete`	All required items are complete
`content:dismiss`	Checklist panel was closed

The admin analytics dashboard shows:

Per-item completion rates (which items do users complete first, which do they skip?)
Overall checklist completion rate
Average time to complete the full checklist
Drop-off analysis (which items cause users to abandon the checklist?)

Best Practices

Keep checklists short -- 3 to 6 items is the sweet spot. More than 7 items feels overwhelming.
Order items by importance -- Put the most impactful actions first. Users are most motivated at the start.
Use event-based completion -- Track actual user actions rather than relying on URL visits alone.
Celebrate completion -- The confetti and completion message create a positive moment that reinforces the behaviour.
Make items actionable -- Every item should have a clear CTA that takes the user directly to where they can complete the task.
Consider required vs optional -- Mark nice-to-have items as required: false so the checklist can complete without them.

Checklists ​

Overview ​

Creating a Checklist ​

Via the Admin Panel ​

Via the API ​

Configuration ​

Checklist Items ​

Completion Criteria ​

Item CTA ​

Launcher ​

Position ​

Style ​

Progress Tracking ​

Completion Celebration ​

Skippable Items ​

Programmatic Control ​

Styling ​

Analytics ​

Best Practices ​

Checklists

Overview

Creating a Checklist

Via the Admin Panel

Via the API

Configuration

Checklist Items

Completion Criteria

Item CTA

Launcher

Position

Style

Progress Tracking

Completion Celebration

Skippable Items

Programmatic Control

Styling

Analytics

Best Practices