Developer Docs

Quick reference guides with props tables, usage examples, and best practices for rapid development

Components

Form Components

Display Components

Feedback Components

Layout Components

Navigation Components

Components/Docs/CheckList

CheckList

Multi-select lists with integrated checkboxes. Perfect for task lists, permissions, settings, and any scenario requiring multiple selections with visual feedback.

Quick Example

First Item

Second Item

Third Item

Fourth Item

Selected: 1 item

🔧 Props Reference

All available props for the CheckList component:

Prop	Type	Default	Description
items	Array	[]	Items array (objects with id, label, description, badge)
checkedItems	van.State<Array>	van.state([])	Array of checked item IDs
onCheckChange	Function	null	Callback when checked state changes: (checkedIds, item) => {}
size	string	'md'	Size variant: 'sm', 'md', 'lg'
variant	string	'default'	Style variant: 'default', 'card', 'minimal'
class	string	''	Additional CSS classes

Item Object Structure

Prop	Type	Default	Description
id	string \| number	index	Unique identifier (uses array index if not provided)
label	string	required	Primary text for the item
title	string	undefined	Alternative to label
description	string	undefined	Optional secondary text
badge	Object	undefined	Badge object (see Badge component props)

💻 Basic Usage

Simple checklist with item selection:

First Item

Second Item

Third Item

Fourth Item

const checkedItems = van.state([]);

const items = [
  { id: 1, label: 'First Item' },
  { id: 2, label: 'Second Item' },
  { id: 3, label: 'Third Item' }
];

CheckList({
  items,
  checkedItems
})

// Access checked items
console.log(checkedItems.val); // [1, 3] if items 1 and 3 are checked

📝 With Descriptions

Add descriptions to provide context for each item:

Review pull requests

Check code quality and tests

Update documentation

Add examples for new components

Fix responsive issues

Test on mobile devices

Deploy to staging

Run smoke tests after deployment

const tasks = [
  {
    id: 1,
    label: 'Review pull requests',
    description: 'Check code quality and tests'
  },
  {
    id: 2,
    label: 'Update documentation',
    description: 'Add examples for new components'
  },
  {
    id: 3,
    label: 'Fix responsive issues',
    description: 'Test on mobile devices'
  }
];

CheckList({
  items: tasks,
  checkedItems: van.state([1, 3])  // Pre-check items 1 and 3
})

🎨 Variants

Three visual styles to match your design context:

Default (Bordered)

First Item

Second Item

Third Item

CheckList({ items, variant: 'default' })

Card (With Shadow)

First Item

Second Item

Third Item

CheckList({ items, variant: 'card' })

Minimal (Spaced)

First Item

Second Item

Third Item

CheckList({ items, variant: 'minimal' })

📏 Size Variants

Three size options for different use cases:

Extra Small

First Item

Second Item

CheckList({ items, size: 'xs' })

Small

First Item

Second Item

CheckList({ items, size: 'sm' })

Medium (Default)

First Item

Second Item

CheckList({ items, size: 'md' })

Large

First Item

Second Item

CheckList({ items, size: 'lg' })

🔔 With Badges

Display counts or status indicators with badges:

Inbox

Unread messages

Important

Flagged items

Check Change Handler

const checkedItems = van.state([]);

CheckList({
  items,
  checkedItems,
  onCheckChange: (checkedIds, item) => {
    console.log('Checked IDs:', checkedIds);
    console.log('Changed item:', item);

    // Example: Show toast
    if (checkedIds.includes(item.id)) {
      showToast(`Checked: ${item.label}`, 'success');
    } else {
      showToast(`Unchecked: ${item.label}`, 'info');
    }
  }
})

Helper Actions (Select All/None)

Read

View files and folders

Write

Create and edit files

Delete

Remove files and folders

Share with other users

Selected: 2 of 4

const checkedItems = van.state([]);
const items = [ /* your items */ ];

div(
  // Action buttons
  div(
    { class: 'flex gap-2 mb-4' },
    Button({
      onclick: () => checkedItems.val = items.map(item => item.id)
    }, 'Select All'),
    Button({
      onclick: () => checkedItems.val = []
    }, 'Clear All')
  ),

  // CheckList
  CheckList({ items, checkedItems }),

  // Status text
  p(`Selected: ${checkedItems.val.length} of ${items.length}`)
)

⚡️ Best Practices

✓ Do This

✓Use unique IDs for items

✓Provide descriptive labels

✓Use descriptions for clarity

✓Show selection count

✓Provide Select All/Clear All

✓Use onCheckChange for side effects

✓Use badges for counts/status

✗ Avoid This

✗Use for single selection (use RadioButton)

✗Have too many items (use search/filter)

✗Forget to persist checked state

✗Hide selection count

✗Use long descriptions (1 line max)

✗Nest CheckLists

✗Forget to handle empty state

✨ Key Features

★

Integrated Checkboxes

Built-in Checkbox components with proper sizing

★

Visual Feedback

Blue accent highlight for checked items

★

Badge Support

Show counts, status, or metadata

★

Descriptions

Optional secondary text for context

★

Click Anywhere

Entire row is clickable, not just checkbox

★

Reactive State

van.state for automatic UI updates

💡 Common Use Cases

Common patterns for implementing CheckList in your applications:

1. Task List / Todo

const tasks = [
  { id: 1, label: 'Complete project proposal' },
  { id: 2, label: 'Review code changes' },
  { id: 3, label: 'Update documentation' },
  { id: 4, label: 'Deploy to production' }
];

const completedTasks = van.state([]);

div(
  h3('My Tasks'),

  CheckList({
    items: tasks,
    checkedItems: completedTasks,
    onCheckChange: (checked) => {
      const progress = (checked.length / tasks.length * 100).toFixed(0);
      showToast(`Progress: ${progress}%`, 'info');
    }
  }),

  p(`Completed: ${completedTasks.val.length}/${tasks.length}`)
)

2. Permission Settings

const permissions = [
  {
    id: 'read',
    label: 'Read',
    description: 'View files and folders'
  },
  {
    id: 'write',
    label: 'Write',
    description: 'Create and edit files'
  },
  {
    id: 'delete',
    label: 'Delete',
    description: 'Remove files and folders'
  },
  {
    id: 'share',
    label: 'Share',
    description: 'Share with other users'
  }
];

const userPermissions = van.state(['read', 'write']);

div(
  h3('User Permissions'),

  CheckList({
    items: permissions,
    checkedItems: userPermissions,
    variant: 'card'
  }),

  Button({
    onclick: async () => {
      await savePermissions(userPermissions.val);
      showToast('Permissions saved', 'success');
    }
  }, 'Save Changes')
)

3. Feature Toggles

const features = [
  {
    id: 'notifications',
    label: 'Email Notifications',
    description: 'Receive updates via email'
  },
  {
    id: 'darkMode',
    label: 'Dark Mode',
    description: 'Use dark color scheme'
  },
  {
    id: 'analytics',
    label: 'Analytics',
    description: 'Help us improve with usage data'
  }
];

const enabledFeatures = van.state(['notifications']);

CheckList({
  items: features,
  checkedItems: enabledFeatures,
  onCheckChange: (enabled, feature) => {
    // Auto-save on change
    saveSettings({ [feature.id]: enabled.includes(feature.id) });
  }
})

4. Bulk Actions

const services = [
  { id: 1, label: 'Lawn Mowing', badge: { label: 'Active' } },
  { id: 2, label: 'Dog Walking', badge: { label: 'Active' } },
  { id: 3, label: 'Tutoring', badge: { label: 'Paused' } },
  { id: 4, label: 'Snow Removal', badge: { label: 'Active' } }
];

const selectedServices = van.state([]);

div(
  h3('My Services'),

  CheckList({
    items: services,
    checkedItems: selectedServices
  }),

  // Bulk action buttons
  () => selectedServices.val.length > 0 ? div(
    { class: 'flex gap-2 mt-4' },
    Button({
      onclick: () => pauseServices(selectedServices.val)
    }, `Pause (${selectedServices.val.length})`),
    Button({
      onclick: () => deleteServices(selectedServices.val)
    }, `Delete (${selectedServices.val.length})`)
  ) : ''
)

5. Filter/Export Selection

const exportFields = [
  { id: 'name', label: 'Name', description: 'User full name' },
  { id: 'email', label: 'Email', description: 'Email address' },
  { id: 'phone', label: 'Phone', description: 'Phone number' },
  { id: 'location', label: 'Location', description: 'City and state' },
  { id: 'joinDate', label: 'Join Date', description: 'Account creation date' }
];

const selectedFields = van.state(['name', 'email']);

div(
  h3('Select Fields to Export'),

  CheckList({
    items: exportFields,
    checkedItems: selectedFields,
    variant: 'minimal'
  }),

  Button({
    class: 'mt-4',
    onclick: () => exportData(selectedFields.val),
    disabled: () => selectedFields.val.length === 0
  }, () => `Export (${selectedFields.val.length} fields)`)
)

🔧 Programmatic Control

Control CheckList state programmatically for dynamic interactions:

Check/Uncheck Items

const checkedItems = van.state([]);

// Check specific items
checkedItems.val = [1, 3, 5];

// Add items
checkedItems.val = [...checkedItems.val, 2];

// Remove items
checkedItems.val = checkedItems.val.filter(id => id !== 3);

// Toggle item
const toggleItem = (id) => {
  checkedItems.val = checkedItems.val.includes(id)
    ? checkedItems.val.filter(i => i !== id)
    : [...checkedItems.val, id];
};

Conditional Pre-checking

// Pre-check items based on condition
const checkedItems = van.state(
  items
    .filter(item => item.isDefault)
    .map(item => item.id)
);

// Pre-check from saved settings
const savedSelections = await loadUserSettings();
const checkedItems = van.state(savedSelections || []);

♿ Accessibility

CheckList is built with accessibility in mind:

✓Each checkbox has proper labels from item.label

✓Entire row is clickable with keyboard support

✓Visual feedback for checked state (blue accent)

✓Screen reader announces checked/unchecked state

✓Focus visible with ring styles

✓Proper checkbox semantics with native input[type=checkbox]

Explore More Components

Browse other component categories