Checkboxes

A group of options where any number can be selected at once.

checkboxes renders a stack of checkbox options. Use it when someone can pick zero, one, or several options from a short list: an actions row or section accessory for a live toggle, or an input block to collect a value in a modal or Home tab.

Fields

Each option is an Option object:

Examples

With initial options checked

The preview above starts with “Email me” already checked, using initial_options.

Without initial options

Every option starts unchecked, and onAction doesn’t fire until the first check.

With option descriptions

A description adds a second, muted line under the option’s label.

As a section accessory

As a section accessory, the group stacks below the section’s text instead of sitting beside it.

In an input block

With a confirmation dialog

The dialog only appears when checking an option on. Unchecking never asks for confirmation. See Confirmation dialogs.

Interactivity

Checking or unchecking an option (after any confirm dialog is accepted) calls onAction with the full, current set of checked options under selected_options, not just the one that changed:

{
  "type": "checkboxes",
  "action_id": "channels",
  "block_id": "notify",
  "action_ts": "1706000000.000100",
  "selected_options": [
    { "text": { "type": "plain_text", "text": "Email me" }, "value": "email" },
    { "text": { "type": "plain_text", "text": "Notify #general" }, "value": "general" }
  ]
}

Reading the value

Checkboxes write to state.values on mount (reporting initial_options, exactly like Slack does when the surface loads) and again on every change:

{
  "notify": {
    "channels": {
      "type": "checkboxes",
      "selected_options": [
        { "text": { "type": "plain_text", "text": "Email me" }, "value": "email" }
      ]
    }
  }
}

An unchecked group with no initial_options reports selected_options: [], not a missing key.

Related