Select menu elements
Dropdowns for a fixed list, an external data source, or Slack's own directory of users, conversations, and channels.
A select menu is a dropdown that reports one chosen value (*_select) or several
(multi_*_select). Slack has five data sources: static, external, users, conversations,
and channels, each with its own single- and multi-select type, and its own field name in
state.values. Use it wherever a button’s fixed set of choices isn’t enough: picking a user to
assign, a channel to post to, or an option from a list you don’t want to spell out as buttons.
Fields
Every select shares these:
typestring
One of static_select, external_select, users_select, conversations_select, channels_select, or the multi_ prefixed variant of each.
stringaction_idstring
Identifies this element in block_actions and state.values.
stringplaceholder?PlainTextElement
Shown in the closed control when nothing is selected. Without one, a static_select shows Slack's default, "Pick an option".
PlainTextElementconfirm?ConfirmationDialog
Shows a confirm dialog before the selection is committed.
ConfirmationDialogfocus_on_load?boolean
Focuses this element when the surface loads. Only one element per view should set it.
booleanfalseA multi_*_select additionally accepts:
max_selected_items?number
Caps how many items can be picked at once. Renders as Slack's "You can select up to N items." hint in an input block. A request built by hand can carry more, so check the count on your server.
numberEach data source adds its own fields, covered in its section below.
Examples
Static select
Options come from a fixed list you provide: options, or option_groups to label clusters of
them. Slack caps options and option_groups at 100 entries each (see Limits),
and a select can carry one or the other, never both.
Like Slack’s, a single static_select or external_select is typed into: its field is a text
input (role="combobox") that shows the chosen option. Clicking it opens the list under the field
with the chosen option highlighted, or the first one, with or without option_groups. A chosen
option is marked with a check and aria-selected, and the field
shows the placeholder while the list is open. In an input block the list is a little wider than
the field. Typing narrows the list to the options with a word that starts with what you typed
(“york” finds “New York”, “ork” finds nothing), so there’s no separate search box; an
external_select searches the app instead. When nothing matches, the list says “😕 Nothing could
be found.”, Slack’s wording, emoji included, so a screen reader reads the emoji’s name too. Escape
and Tab close the list and keep what you typed, for the next time it opens.
The highlight works as in Slack. A list opened with the keyboard, and the first match while you
type, starts on a lighter highlight (grey) with an Enter key on the row, and Enter picks it. The
first arrow key turns it into the keyboard highlight (blue), and later presses move it. In a
typed-into select, either highlight makes the row the field’s aria-activedescendant, so a screen
reader announces it as it moves. Option groups get a heading each, with their options indented under it and a rule between
groups.
The single users, conversations and channels selects are typed into the same way. The
multi-selects open from a button, with a search box where there’s something to search, except
multi_external_select: as in Slack, you type into its field after the chosen options, and its list
shows only the app’s options or the minimum-query hint. A
multi-select ticks the options it already has, in place; like Slack’s, its list doesn’t repeat them
in a separate “Selected” group. In an input block its list is a little wider than
the field. Tabbing into a multi-select in an input block opens its list, as Slack’s does. Picking
with Enter keeps a multi-select’s list open for the next pick; a click closes it and leaves the field
focused, with its focus ring. A single static select also stays focused after a click pick, as
Slack’s does; a users, conversations or channels select lets focus go. An external_select asks for “Type a minimum of
N characters to see options.” until the query reaches its min_query_length.
That message, “Nothing could be found.” and the rows themselves are list content, not a live
region: a screen reader reads them when it moves into the list, not when they change. The number of
results isn’t announced. If a minimum query length matters to your users, say so in the input
block’s hint as well.
As an input block, a multi-static-select shows selected options as removable chips inside the
field, and grows to fit them. Empty, any multi-select in an input block shows its placeholder
across the whole field and cuts it off after the first line at a whole word, with no “…”, as Slack
does. A chip’s “x” removes it on click, or with Enter or Space once it has keyboard focus; either
way the action fires with the remaining selected_options:
New issue
As a section accessory, a multi-select (static, users, conversations or channels) is a small
button, as in Slack: it reads the placeholder (“Select options”), then “2 selected” once options are
chosen. A placeholder over 30 characters shows its first 30 and “…” there. Clicking it opens a dialog
titled with the placeholder, on one line that ends in “…” when it doesn’t fit, with the field and
its chips. The empty field shows the placeholder again, cut off after its first line. A chip shows a chosen conversation or channel by its resolved name, or as a “Private
channel” pill when nobody resolves its ID, as Slack does. Its
list holds the options, or for a users, conversations or channels select the resolvers.directory
entries; typing filters it by name. In a directory select, Enter with no row highlighted adds
what you typed as an ID, which stands in for Slack’s search of the workspace.
A click opens the list with nothing highlighted; the first arrow key highlights the first option,
and hovering a row doesn’t highlight it.
The list stays open while you pick, and nothing is sent until Confirm, which fires one action
with every pick (selected_options, selected_users and so on; a static select adds its
placeholder). Cancel, the close button and Escape discard the picks. Focus moves to the
dialog itself rather than to its field, as it does in Slack; Tab reaches the close button and then
the field. Focus returns to the button when the dialog closes.
options?PlainTextOption[]
Up to 100 options. Omit if option_groups is set.
PlainTextOption[]option_groups?OptionGroup[]
Up to 100 labeled groups of options, each up to 100 options. Omit if options is set.
OptionGroup[]initial_option?PlainTextOption
Preselected on load. Must exactly match one entry in options/option_groups, as Slack requires. If no option has its value, the field still shows its text and state reports it, but no row is checked. Single-select only.
PlainTextOptioninitial_options?PlainTextOption[]
Preselected on load, one per chip. Multi-select only.
PlainTextOption[]External select
Options aren’t provided up front. Slack (and this library) asks your app for them as the person
types, via a block_suggestion request. Give the <BlockKitProvider> an onOptions handler; it’s
called with the same payload Slack would send your app’s options load URL, and its return value is
what fills the menu.
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
const fruits = ["Apple", "Banana", "Cherry", "Grape", "Mango", "Orange", "Peach", "Pear"];
function FruitPicker() {
return (
<BlockKitProvider
onOptions={({ value }) => ({
options: fruits
// `value` is whatever was typed: cap it before it reaches a real search.
.filter((fruit) => fruit.toLowerCase().startsWith(value.slice(0, 100).toLowerCase()))
.slice(0, 100) // Slack accepts at most 100 options
.map((fruit) => ({
text: { type: "plain_text", text: fruit },
value: fruit.toLowerCase(),
})),
})}
>
<Message
blocks={[
{
type: "actions",
block_id: "fruit",
elements: [
{
type: "external_select",
action_id: "fruit",
placeholder: { type: "plain_text", text: "Favorite fruit" },
min_query_length: 2,
},
],
},
]}
/>
</BlockKitProvider>
);
}
The request looks like this (see Interactivity below for the full shape):
{
"type": "block_suggestion",
"action_id": "fruit",
"block_id": "fruit",
"value": "ap",
"container": { "type": "message", "message_ts": "..." }
}
Your handler answers with { options } or { option_groups }, the same shapes as a static
select’s, built from SuggestionOption objects (text, value, optional description/url).
The Preview above already answers external_select from a fixed fruit list, so you can try typing
without wiring up onOptions yourself.
min_query_length sets how many characters must be typed before the request fires:
initial_option?PlainTextOption
Preselected on load. Single-select only.
PlainTextOptioninitial_options?PlainTextOption[]
Preselected on load. Multi-select only.
PlainTextOption[]min_query_length?number
Fewest characters typed before a block_suggestion request fires.
number3A multi-external-select combines max_selected_items with the same lookup, and can start with
options already picked via initial_options:
New issue
You can select up to 3 items.
Users select
Populated from Slack’s own user directory: there’s nothing to pass for the option list itself,
only which user (if any) starts selected. Outside Slack, the list comes from the provider’s
resolvers.directory, which returns the people and channels to offer for "users",
"conversations" or "channels". Each row is drawn as Slack’s: an avatar, the bold name, “(you)”
for the signed-in user, a badge such as AGENT, the presence icon and the full name. Channels show
a # or a lock. A chosen entry looks the same in a single select’s field. In a multi-select’s chip,
a person gets a smaller avatar, and “(you)” when it’s the signed-in user, and a channel its # or
lock. Without a directory the list says
“😕 Nothing could be found.”
The directory usually comes from users.list and conversations.list, which need the bot token, so
fetch it on your server and pass the entries to the browser as data: from a Server Component, or a
route of your own. Never call them from the browser with a WebClient; see
Keep the bot token on the server.
<BlockKitProvider
resolvers={{
directory: (source) =>
source === "channels"
? [{ type: "channel", id: "C0123456789", name: "general" }]
: [{ type: "user", id: "U0123456789", name: "Ada Lovelace", self: true, presence: "active" }],
}}
>
A conversations select applies its filter to the directory: include keeps people (im),
private or public channels, and exclude_bot_users drops entries marked bot. A directory
entry is a person or a channel, never a group DM, so mpim keeps nothing, and
exclude_external_shared_channels has nothing to act on. A chosen ID the directory doesn’t list
comes first in the list, shown the same way as in the closed field: its resolved name, or for an ID
nobody resolves, a loading skeleton for a person, a “Private channel” pill for a channel and a blank
row for a conversation.
As an input block, multi_users_select starts with initial_users already selected as chips:
Code review
initial_user?string
A user ID preselected on load. Single-select only.
stringinitial_users?string[]
User IDs preselected on load, one chip each. Multi-select only.
string[]The package can’t look up a real workspace directory. The previews on this page resolve three demo
people (U0ADA, U0GRACE and U0ALAN); any other user ID renders as Slack’s loading skeleton, in
the field and in a multi-select’s chip, rather than the raw ID, as Block Kit Builder does for a user
it can’t find. The skeleton stays until a resolver names the ID; there’s no timeout. It has no
visible text, so a screen reader hears the ID instead of a name. Pass a resolvers.user function (or list the person in
resolvers.directory) to show the name to everyone.
Conversations select
Populated from every conversation the person can see: public and private channels, DMs, and group
DMs. In Slack, default_to_current_conversation preselects the conversation the person was viewing
when they opened the modal, if there is one; this package has no current conversation, so the flag
preselects nothing. filter narrows the list Slack offers.
A filter object restricts which conversation types Slack shows, and can drop bot users or
external shared channels from the list:
initial_conversation?string
A conversation ID preselected on load. Slack documents that it takes precedence over default_to_current_conversation. Single-select only.
stringinitial_conversations?string[]
Conversation IDs preselected on load. Slack documents the opposite of the single select here: they're ignored when default_to_current_conversation is set. This package has no current conversation and always preselects them. Multi-select only.
string[]default_to_current_conversation?boolean
Preselects the conversation the surface was opened from, if any.
booleanfalsefilter?ConversationFilter
Narrows the list Slack offers. See below.
ConversationFilterfilter’s fields:
include?("im" | "mpim" | "private" | "public")[]
Only these conversation types are offered. Omit to allow all four.
("im" | "mpim" | "private" | "public")[]exclude_bot_users?boolean
Drops bot users from the list.
booleanfalseexclude_external_shared_channels?boolean
Drops Slack Connect (externally shared) channels from the list. Doesn't exclude external users from shared channels that remain.
booleanfalseChannels select
The same idea as a conversations select, restricted to public channels the person is a member of.
It has no filter or default_to_current_conversation.
Post to
As an actions element, a multi-channels-select with items already picked collapses to a
content-sized outline button rather than the full-width dropdown a single-select uses:
initial_channel?string
A channel ID preselected on load. Single-select only.
stringinitial_channels?string[]
Channel IDs preselected on load. Multi-select only.
string[]Interactivity
A select sends a block_actions action as soon as an option is picked or a chip removed (after its
confirm dialog, if it has one), with two exceptions:
- In an
inputblock it sends one only when the block setsdispatch_action: true. Otherwise its value waits instateuntil the modal is submitted. - A multi-select in a section accessory (other than
multi_external_select) collects picks in its dialog and sends one action, with all of them, when Confirm is pressed.
The field name in both the block_actions action and state.values depends on the data source and
whether it’s single- or multi-select:
| Source | Single | Multi |
|---|---|---|
static_select |
selected_option |
selected_options |
external_select |
selected_option |
selected_options |
users_select |
selected_user |
selected_users |
conversations_select |
selected_conversation |
selected_conversations |
channels_select |
selected_channel |
selected_channels |
A static_select/external_select reports the full option object; the other sources report just
the id string.
Single static select, from the priority example above:
{
"type": "static_select",
"action_id": "priority",
"block_id": "assign",
"selected_option": {
"text": { "type": "plain_text", "text": "High", "emoji": true },
"value": "high"
}
}
A static select with a placeholder sends it back in the action too, and a single one with an
initial_option echoes that as well. A users, conversations or channels select sends no
placeholder; it echoes its initial_user, initial_conversation or initial_channel (or the
plural for a multi-select) instead. Both are what Slack sends.
state.values.assign.priority holds the same selected_option shape, tagged with type:
{
"type": "static_select",
"selected_option": {
"text": { "type": "plain_text", "text": "High", "emoji": true },
"value": "high"
}
}
Multi users select, from the reviewers example above, after picking Ada and Grace. Its input
block doesn’t set dispatch_action, so this is the action it would send if it did; as it stands,
the same selected_users waits in state.values.reviewers.value for the submission:
{
"type": "multi_users_select",
"action_id": "value",
"block_id": "reviewers",
"selected_users": ["U0ADA", "U0GRACE"]
}
A conversations select with a filter, from the private-channels example:
{
"type": "multi_conversations_select",
"action_id": "conversations",
"block_id": "notify",
"selected_conversations": ["C0DESIGN"]
}
Reading it in React
import { BlockKitProvider, Message } from "@nkootstra/block-kit";
<BlockKitProvider
onAction={(action) => {
if (action.action_id === "priority") {
console.log(action.selected_option.value); // "high"
}
// The single users_select from the code review example.
if (action.action_id === "reviewer") {
console.log(action.selected_user); // "U0ADA"
}
}}
>
<Message blocks={blocks} />
</BlockKitProvider>;
block_suggestion (external select)
An external_select/multi_external_select additionally sends a block_suggestion request to
onOptions while the person types, once the query reaches min_query_length:
interface BlockSuggestionPayload {
type: "block_suggestion";
action_id: string;
block_id: string;
value: string; // what's typed so far
container: { type: "message" | "view" /* ... */ };
// team, user, api_app_id: identity fields, like any Slack payload. `token` is Slack's
// deprecated verification token: check the request's signature instead.
}
onOptions returns either flat options or labeled groups:
type OptionsResponse =
| { options: SuggestionOption[] }
| { option_groups: { label: PlainTextElement; options: SuggestionOption[] }[] };
Related
Elements overview
Where each interactive element can live, and how action_id ties it to state.values.
Checkboxes
A fixed set of options with all of them visible at once, instead of a dropdown.
Radio buttons
Like checkboxes, but only one option can be selected.
Overflow menu
A compact “…” menu for a short list of actions rather than data-backed options.