[#checklist]
= Input: Checklist

The `checklist` type argument renders multiple checkboxes from predefined `choices`. Users can select one or more options, and the selected values are passed to your action as a **JSON array string** (for example `["documents","photos"]`). Legacy comma-separated values are rejected.

[source,yaml]
----
actions:
  - title: Backup selected directories
    shell: echo "Backing up: {{ directories }}"
    arguments:
      - name: directories
        title: Directories to back up
        type: checklist
        choices:
          - title: Documents
            value: documents
          - title: Photos
            value: photos
          - title: Music
            value: music
        default: '["documents","photos"]'
----

.Checklist argument form with Documents and Photos selected by default.
image::args/checklist/checklist.png[]

When the example above runs with Documents and Photos selected, the shell command becomes:

[source,shell]
----
echo "Backing up: [\"documents\",\"photos\"]"
----

== Select all / Select none

The web interface includes **Select all** and **Select none** controls above the checkbox list.

== Empty selections

If no options are selected, the argument value is an empty string. Use `rejectNull: true` when at least one selection is required.

[source,yaml]
----
arguments:
  - name: directories
    type: checklist
    rejectNull: true
    choices:
      - value: documents
      - value: photos
----

== Choice values

Choice `value` fields may contain commas; selections are encoded as JSON, not joined with commas.

Each `title` is shown in the web interface. If a submitted segment matches a choice `title`, OliveTin maps it to the corresponding `value` before validation, matching the behaviour of xref:args/input_checkbox.adoc[checkbox] arguments with choices.

== Using Entities

Checklist options can be generated from entities, using the same pattern as xref:args/input_dropdown.adoc#args-dropdown-entities[entity-backed dropdowns]. Define one choice template and set `entity` to the entity type name:

[source,yaml]
----
actions:
  - title: Restart selected containers
    shell: 'docker restart {{ containers }}'
    arguments:
      - name: containers
        title: Containers to restart
        type: checklist
        entity: container
        choices:
          - value: '{{ container.Names }}'
            title: '{{ container.Names }}'

entities:
  - file: entities/containers.json
    name: container
----

OliveTin expands the template once per entity instance and renders each result as a checkbox. Selected values are still passed as a JSON array string.

IMPORTANT: Like dropdowns, checklist arguments with `entity` must define **exactly one** choice template. Combining `entity` with multiple static choices is rejected on startup.