# Multi-select menu element Allows users to select multiple items from a list of options. Like select menus, multi-select menus include type-ahead search. | | | |---|---| | **Type** | `multi_static_select` | | **Available in** | Messages, Modals, Home tab | | **Works in blocks** | [Section block](https://workstation.repzo.com/docs/developers/block-kit/blocks/section-block), [Actions block](https://workstation.repzo.com/docs/developers/block-kit/blocks/actions-block), [Input block](https://workstation.repzo.com/docs/developers/block-kit/blocks/input-block) | ## Usage There are five kinds of multi-select menu, depending on where the options come from. They share most fields; the fields table marks the ones that belong to a single kind. | Type | Options come from | Value in `block_actions` | |---|---|---| | `multi_static_select` | the `options` or `option_groups` you send | `selected_options` — option objects | | `multi_external_select` | your app, as the reader types (`block_suggestion`, below) | `selected_options` — option objects | | `multi_users_select` | the active members of the workspace | `selected_users` — user ids | | `multi_conversations_select` | the channels and DMs the reader can see, narrowed by `filter` | `selected_conversations` — channel ids | | `multi_channels_select` | the channels the reader can see | `selected_channels` — channel ids | Every change sends your app a `block_actions` payload carrying the whole current selection: ```json { "type": "multi_static_select", "action_id": "deal_tags", "block_id": "deal_d2291", "placeholder": { "type": "plain_text", "text": "Add tags" }, "selected_options": [ { "text": { "type": "plain_text", "text": "Upsell" }, "value": "upsell" }, { "text": { "type": "plain_text", "text": "Multi-year" }, "value": "multi_year" } ], "action_ts": "1793786400.000000" } ``` Option labels are copied from your element (or from what your app served), never from the reader's client. People must be active members of the workspace, and conversations must be ones the reader can see. In a submitted view, more than `max_selected_items` choices is refused with "Choose at most N.". See the [button element](https://workstation.repzo.com/docs/developers/block-kit/elements/button-element) for the rest of the payload. The current value is also reported in `state.values[block_id][action_id]` (as `{ "type": …, }`) of every later interaction with the same message or view. Inside an [input block](https://workstation.repzo.com/docs/developers/block-kit/blocks/input-block), changing the value sends nothing on its own: your app reads it from `view.state.values` in the `view_submission` payload. Set `dispatch_action: true` on the input block to also receive a `block_actions` payload on every change. ### Loading options from your app (`block_suggestion`) An external select asks your app for options as the reader types. Once the reader has typed `min_query_length` characters (default `3`), Repzo POSTs a signed `block_suggestion` payload to your app's subscription for the `block_suggestion` event — or, if it has none, to the subscription that receives `block_actions` (Slack's single Request URL): ```json { "type": "block_suggestion", "team": { "id": "" }, "user": { "id": "", "username": "", "name": "", "team_id": "" }, "api_app_id": "", "container": { "type": "message", "message_ts": "", "channel_id": "", "is_ephemeral": false }, "channel": { "id": "" }, "block_id": "account_picker", "action_id": "choose_account", "value": "north" } ``` In a modal or the Home tab, `container` is `{ "type": "view", "view_id": … }` and the payload also carries the `view`. Answer **within 3 seconds** with `{ "options": [ … ] }` or `{ "option_groups": [ … ] }` (option objects; up to 100 options in a list or group). Option values longer than 150 characters are dropped, labels and descriptions are cut to 75 characters, and an option's `url` is ignored. If your app doesn't answer in time, the reader sees an error and can type again. A reader can only choose an option your app served them (Repzo remembers each reader's suggestions for an hour) or the element's initial option(s). Anything else is refused before your app hears about it, so you can trust every `value` you receive. ## Fields | Field | Type | Description | Required? | |---|---|---|---| | `type` | String | The type of element: `multi_static_select`, `multi_external_select`, `multi_users_select`, `multi_conversations_select` or `multi_channels_select`. | Required | | `action_id` | String | An identifier for the action triggered when the selection changes. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other `action_id`s in the containing block. Maximum length is 255 characters. If you leave it out, Repzo generates one. | Optional | | `options` | Array of [Option object](https://workstation.repzo.com/docs/developers/block-kit/objects/option-object) | **`multi_static_select` only.** An array of option objects. Maximum number of options is 100 (counting the options inside `option_groups`). Each option's text must be less than 76 characters. If `option_groups` is specified, this field should not be. | Required for `multi_static_select` unless `option_groups` is provided | | `option_groups` | Array of [Option group object](https://workstation.repzo.com/docs/developers/block-kit/objects/option-group-object) | **`multi_static_select` only.** An array of option group objects. If `options` is specified, this field should not be. | Optional | | `initial_options` | Array of [Option object](https://workstation.repzo.com/docs/developers/block-kit/objects/option-object) | **`multi_static_select` and `multi_external_select`.** An array of option objects that exactly match one or more of the options within `options` or `option_groups` (for external menus: options your app would serve). These options will be selected when the menu initially loads. | Optional | | `min_query_length` | Integer | **`multi_external_select` only.** The fewest number of typed characters required before Repzo asks your app for options. The default value is `3`. | Optional | | `initial_users` | String[] | **`multi_users_select` only.** An array of user IDs of any valid users to be pre-selected when the menu loads. | Optional | | `initial_conversations` | String[] | **`multi_conversations_select` only.** An array of one or more IDs of any valid conversations to be pre-selected when the menu loads. | Optional | | `default_to_current_conversation` | Boolean | **`multi_conversations_select` only.** Pre-populates the select menu with the conversation that the user was viewing when they opened the modal, if available. Default is `false`. | Optional | | `filter` | [Conversation filter object](https://workstation.repzo.com/docs/developers/block-kit/objects/conversation-filter-object) | **`multi_conversations_select` only.** A filter object that reduces the list of available conversations using the specified criteria. | Optional | | `initial_channels` | String[] | **`multi_channels_select` only.** An array of one or more IDs of any valid channels to be pre-selected when the menu loads. | Optional | | `max_selected_items` | Integer | Specifies the maximum number of items that can be selected in the menu. Minimum number is 1. | Optional | | `confirm` | [Confirmation dialog object](https://workstation.repzo.com/docs/developers/block-kit/objects/confirmation-dialog-object) | A confirm object that defines an optional confirmation dialog that appears after the selection changes. If the reader cancels, nothing is sent to your app. | Optional | | `focus_on_load` | Boolean | Indicates whether the element will be set to auto focus within the view. Only one element can be set to `true`. Defaults to `false`. | Optional | | `placeholder` | [Text object](https://workstation.repzo.com/docs/developers/block-kit/objects/text-object) | A `plain_text` only text object that defines the placeholder text shown on the menu. Maximum length for the `text` in this field is 150 characters. | Optional | > **How Repzo Chat differs from Slack** > > - `max_selected_items` is enforced when a view is submitted; while picking, and in messages, it isn't a hard limit. > - Channel menus (`channels_select`, `multi_channels_select`) list the public **and private** channels the reader can see; Slack lists public channels only. > - Repzo has public channels, private channels, direct messages (`im`) and group direct messages with two to eight other people (`mpim`). `exclude_external_shared_channels` has no effect because Repzo has no externally shared channels. Without a filter, conversations menus list channels and DMs, group DMs included; channels menus list channels only. `exclude_bot_users` hides DMs with apps. > - Every chosen conversation is checked on the server: it must be one the reader can see and, when `filter.include` is set, of an allowed kind. > - When both `default_to_current_conversation` and `initial_conversations` are set, `initial_conversations` wins (Slack ignores it). > - On the web, an external select starts asking your app after the first typed character even when `min_query_length` is `0`; the mobile app asks as soon as the picker opens. > - Suggestions go to the app's `block_suggestion` subscription, or to its `block_actions` subscription when it has none — there is no separate Options Load URL to configure. > - `focus_on_load` is accepted but not applied to this element yet. ## Examples ### A static multi-select in a section ```json { "blocks": [ { "type": "section", "block_id": "deal_d2291", "text": { "type": "mrkdwn", "text": "*Northwind Traders — Expansion 2027*\nStage: Negotiation · Amount: *$64,000*" }, "accessory": { "type": "multi_static_select", "action_id": "deal_tags", "placeholder": { "type": "plain_text", "text": "Add tags" }, "initial_options": [ { "text": { "type": "plain_text", "text": "Upsell" }, "value": "upsell" } ], "options": [ { "text": { "type": "plain_text", "text": "Upsell" }, "value": "upsell" }, { "text": { "type": "plain_text", "text": "Multi-year" }, "value": "multi_year" }, { "text": { "type": "plain_text", "text": "Needs legal review" }, "value": "legal_review" }, { "text": { "type": "plain_text", "text": "Strategic account" }, "value": "strategic" } ] } } ] } ``` ### People and channel pickers in a form This example belongs in a modal view — the screenshot shows it in a modal. ```json { "blocks": [ { "type": "input", "block_id": "kickoff_attendees", "label": { "type": "plain_text", "text": "Who should join the kick-off?" }, "element": { "type": "multi_users_select", "action_id": "attendees", "max_selected_items": 5, "placeholder": { "type": "plain_text", "text": "Select people" } } }, { "type": "input", "block_id": "kickoff_channels", "optional": true, "label": { "type": "plain_text", "text": "Post the summary in" }, "element": { "type": "multi_conversations_select", "action_id": "summary_channels", "default_to_current_conversation": true, "filter": { "include": [ "public", "private" ] }, "placeholder": { "type": "plain_text", "text": "Select channels" } } } ] } ``` ## Related - [Block elements](https://workstation.repzo.com/docs/developers/block-kit/elements) - [Block Kit overview](https://workstation.repzo.com/docs/developers/block-kit)