---
title: Checklist
description: "Provides a checklist UI with optional progress and storage modes. The field stores selected items as an array of indexes or labels based on the chosen mode. ## Use Cases - Track content review tasks - Collect completion status for…"
url: "https://racmanuel.dev/docs/custom-fields-booster/checklist/"
updated: "2026-02-24"
category: Custom Fields Booster
tags:
  - Free
---

# Checklist

Provides a checklist UI with optional progress and storage modes.

The field stores selected items as an array of indexes or labels based on the chosen mode.

## Use Cases

- Track content review tasks
- Collect completion status for onboarding steps
- Record compliance checks
- Store per-entry progress lists
- Maintain editorial checklists

## Field Preview

A list of checkboxes with optional progress text and a progress bar.

## How to Use

1. Add the Checklist field to a Field Group.
2. Enter **Items** (one per line).
3. Enable **Show progress** if desired.
4. Choose **Columns** (1 or 2).
5. Toggle **Editable**.
6. Select **Store value as** (Number or Name).
7. Save the Field Group and edit a post.

## Field Settings

| Setting | Description | Default |
| --- | --- | --- |
| Items | One item per line | Item 1, Item 2, Item 3 |
| Show progress | Show completed count and a progress bar | 1 |
| Columns | Layout columns for items (1 or 2) | 1 |
| Editable | Allow editors to check/uncheck items | 1 |
| Store value as | Save by item position or item text | index |

Notes:

- Stored values are normalized, de-duplicated, and sorted.

## Value & Storage

Saved as: Post meta

Storage type: Array

Return format: array

REST format: not specified

Saved structure:

- Array of integers (1-based positions) when store mode is `index`
- Array of strings (item labels) when store mode is `label`

Important details:

- Invalid values are discarded during normalization.
- Required validation enforces at least one selection when enabled.

## Output Examples

### PHP

```php
$selected = get_field('my_checklist');

if (is_array($selected)) {
    foreach ($selected as $item) {
        echo esc_html((string) $item);
    }
}
```

### Twig

```php
{% set selected = fn('get_field', 'my_checklist') %}
{% if selected %}
  {% for item in selected %}
    {{ item|e }}
  {% endfor %}
{% endif %}
```

## Compatibility

- Repeaters
- Flexible Content
- Options Pages
- Frontend forms (acf_form)
- REST API
- Multisite

## Hooks (Developer)

### Hooks Summary

| Hook | Type | Purpose |
| --- | --- | --- |
| custom_fields_booster_checklist_defaults | Filter | Modify default settings. |
| custom_fields_booster_checklist_supports | Filter | Modify ACF support flags. |
| custom_fields_booster_checklist_before_settings | Action | Run logic before rendering settings UI. |
| custom_fields_booster_checklist_after_settings | Action | Run logic after rendering settings UI. |
| custom_fields_booster_checklist_before_enqueue | Action | Run logic before enqueuing assets. |
| custom_fields_booster_checklist_after_enqueue | Action | Run logic after enqueuing assets. |
| custom_fields_booster_checklist_before_render | Action | Run logic before rendering UI. |
| custom_fields_booster_checklist_after_render | Action | Run logic after rendering UI. |
| custom_fields_booster_checklist_store_mode | Filter | Override storage mode. |
| custom_fields_booster_checklist_is_editable | Filter | Override editable state. |
| custom_fields_booster_checklist_items | Filter | Modify checklist items. |
| custom_fields_booster_checklist_wrapper_attrs | Filter | Modify wrapper attributes. |
| custom_fields_booster_checklist_progress_template | Filter | Customize progress text. |
| custom_fields_booster_checklist_after_ui | Action | Runs after the checklist UI block. |
| custom_fields_booster_checklist_update_value | Filter | Modify value before save. |
| custom_fields_booster_checklist_item_completed | Action | Fires for each newly completed item on save. |
| custom_fields_booster_checklist_completed_all | Action | Fires when all items are completed on save. |
| custom_fields_booster_checklist_updated_value | Action | Fires after normalization before save. |
| custom_fields_booster_checklist_load_value | Filter | Modify value after loading. |
| custom_fields_booster_checklist_validate_value | Filter | Modify validation result. |
| custom_fields_booster_checklist_format_value | Filter | Modify value returned by `get_field()`. |

### Filters

**Filter:** `custom_fields_booster_checklist_store_mode`

Purpose: Override the storage mode.

When: You need to force a consistent mode across fields.

```php
add_filter('custom_fields_booster_checklist_store_mode', function ($mode, $field, $post_id) {
    return 'label';
}, 10, 3);
```

**Filter:** `custom_fields_booster_checklist_items`

Purpose: Modify the items list.

When: You need to add or remove items dynamically.

```php
add_filter('custom_fields_booster_checklist_items', function ($items, $field, $post_id) {
    $items[] = 'New item';
    return $items;
}, 10, 3);
```

**Filter:** `custom_fields_booster_checklist_update_value`

Purpose: Modify the normalized value before save.

When: You need to transform stored values.

```php
add_filter('custom_fields_booster_checklist_update_value', function ($selected, $value, $post_id, $field, $store_mode) {
    return $selected;
}, 10, 5);
```

### Actions

**Action:** `custom_fields_booster_checklist_after_ui`

Runs after the checklist UI block renders.

```php
add_action('custom_fields_booster_checklist_after_ui', function ($field, $post_id, $selected, $total, $store_mode) {
    // Custom logic.
}, 10, 5);
```

## Assets

This field enqueues assets whenever the input is rendered (admin and frontend via `acf_form()`):

- `admin/js/cfb-field-checklist.js`
- `admin/css/cfb-field-checklist.css`

## REST API

Schema: not specified

## REST Validation

Standard ACF validation only.

## Security & Escaping

- Output escapes attributes and labels in the field UI.
- `escaping_html` support is disabled for this field.

## Notes / Limitations

- Items are re-indexed from 1 based on the configured list.

## Changelog

- 1.0.0 — Initial release