Overview

The controlBlockSelection action gives you full programmatic control over which items are selected inside any block that supports multi-selection. Rather than requiring the user to click each row, you can drive selection state from other events — a "Select All" toolbar button, a checkbox in a parent container, an inbound webhook, or even another block's selection change.

Supported block types include: Table, Repeatable, Kanban, Tree, and any custom block that registers the selectionControl capability.

Parameters

Parameter	Type	Required	Default	Description
blockRef	string	Required (required)	—	The block ID of the target list-type block. Use the block picker in the action editor — only blocks that support selection are shown. If the referenced block does not exist at runtime, the action is a silent no-op.
operation	"select" \| "deselect" \| "toggleAll"	Required (required)	—	`select` adds items to the selection set. `deselect` removes items from it. `toggleAll` selects all items if none or some are selected, and deselects all if every item is currently selected — mirroring a header checkbox.
itemIds	string[]	Optional (optional)	—	An array of item IDs to target. When provided alongside `operation: "select"` or `"deselect"`, only these specific items are affected. IDs are the record's primary key value as a string. Omit when using `selectAll` or `operation: "toggleAll"`.
selectAll	boolean	Optional (optional)	false	When `true` and `operation` is `"select"`, selects every item currently loaded in the block regardless of `itemIds`. When `true` and `operation` is `"deselect"`, clears the entire selection set.

Note: Selection state is available as a block variable. After this action fires, the block's state.selectedIds and state.selectedRows variables are updated synchronously. You can read them in subsequent actions in the same chain — for example, to pass selected IDs to an API call.

How Selection Works Internally

Each list block maintains a selection set — a JavaScript Set<string> of item IDs. The controlBlockSelection action mutates this set and triggers a re-render of the block. No network calls are made. Selection state is page-local and is cleared when the page is unmounted or the data source refreshes (unless the block has Preserve Selection on Refresh enabled in its settings).

When selectAll: true is used, the selection set is populated with the IDs of all records currently in the block's data buffer. If the block is paginated and not all records are loaded, only the loaded records are selected.

Warning: Paginated blocks: selectAll: true selects only the records present in the current page's data buffer. To perform a server-side "select all" across all pages, set a dedicated variable to a sentinel value (e.g. var_selectAllMode: true) and include it in your API call payload, letting the backend handle the full record set.

Step-by-Step Usage Guide

Identify the target block: Open the Page Builder and note the block ID of your Table, Repeatable, or Kanban block. You can find it in the block's Settings → General → Block ID field. Block IDs follow the pattern b_<name>.
Create the action: In the Events panel of your trigger element (e.g. a Button), click + Add Action and choose Control Block Selection from the action type picker.
Configure blockRef and operation: Select the target block using the block picker. Choose the operation: use toggleAll for a header checkbox pattern, select/deselect with itemIds for targeted selection.
Chain downstream actions: Add subsequent actions in the chain that read {{ b_myTable.state.selectedIds }} to perform bulk operations. The selection state is updated before the next action in the chain executes.

Common Use Cases

Bulk Operations

A common pattern is a toolbar with a "Select All" toggle and a "Delete Selected" button. The toggle calls controlBlockSelection with operation: "toggleAll". The delete button reads b_ordersTable.state.selectedIds and passes the array to a delete API action.

Confirm-Before-Delete Pattern

When a user clicks a row-level delete icon, you want to show a confirmation modal that knows which record is targeted. The recommended approach: fire controlBlockSelection with the row's ID first (to record the selection), then open the modal. The modal reads b_myTable.state.selectedRows[0] to display the record name in the confirmation message.

Cross-Block Selection Sync

If your page has a master list and a detail panel that shows a filtered sub-list, you can listen to the master block's onSelectionChange event and fire controlBlockSelection on the detail block, keeping both in sync without a page variable intermediary.

Examples

Toggle all rows in a Table block

{ "actionType": "controlBlockSelection", "payload": { "blockRef": "b_ordersTable", "operation": "toggleAll" } }

Select specific items by ID

{ "actionType": "controlBlockSelection", "payload": { "blockRef": "b_ordersTable", "operation": "select", "itemIds": ["order_101", "order_205", "order_312"] } }

Clear all selections

{ "actionType": "controlBlockSelection", "payload": { "blockRef": "b_ordersTable", "operation": "deselect", "selectAll": true } }

Select all loaded items and pass IDs to an API

// Step 1: Select all { "actionType": "controlBlockSelection", "payload": { "blockRef": "b_ordersTable", "operation": "select", "selectAll": true } } // Step 2: Call a bulk update API { "actionType": "triggerDataSource", "payload": { "dataSourceId": "ds_bulkArchive", "params": { "orderIds": "{{ b_ordersTable.state.selectedIds }}" } } }

Tip: Best practice: Always clear the selection after a bulk operation completes (fire a second controlBlockSelection with deselect + selectAll: true). This prevents stale selection state from affecting subsequent user interactions.

Control Block Selection