Skip to content
Block Kit for React
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Your AppAPP
onActionInteract with the preview.

Fields

Every select shares these:

PropType
typestring

One of static_select, external_select, users_select, conversations_select, channels_select, or the multi_ prefixed variant of each.

Typestring
action_idstring

Identifies this element in block_actions and state.values.

Typestring
placeholder?PlainTextElement

Shown in the closed control when nothing is selected. Without one, a static_select shows Slack's default, "Pick an option".

TypePlainTextElement
confirm?ConfirmationDialog

Shows a confirm dialog before the selection is committed.

TypeConfirmationDialog
focus_on_load?boolean

Focuses this element when the surface loads. Only one element per view should set it.

Typeboolean
Defaultfalse

A multi_*_select additionally accepts:

PropType
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.

Typenumber

Each 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.

Your AppAPP
New issue

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

Labels
Bug

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.

Your AppAPP
Labels
onActionInteract with the preview.
PropType
options?PlainTextOption[]

Up to 100 options. Omit if option_groups is set.

TypePlainTextOption[]
option_groups?OptionGroup[]

Up to 100 labeled groups of options, each up to 100 options. Omit if options is set.

TypeOptionGroup[]
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.

TypePlainTextOption
initial_options?PlainTextOption[]

Preselected on load, one per chip. Multi-select only.

TypePlainTextOption[]

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:

PropType
initial_option?PlainTextOption

Preselected on load. Single-select only.

TypePlainTextOption
initial_options?PlainTextOption[]

Preselected on load. Multi-select only.

TypePlainTextOption[]
min_query_length?number

Fewest characters typed before a block_suggestion request fires.

Typenumber
Default3

A multi-external-select combines max_selected_items with the same lookup, and can start with options already picked via initial_options:

New issue

Tags (up to 3) (optional)

You can select up to 3 items.

Urgent
Options load from the app as you type.

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.

Your AppAPP
Code review

As an input block, multi_users_select starts with initial_users already selected as chips:

Code review

Reviewers
PropType
initial_user?string

A user ID preselected on load. Single-select only.

Typestring
initial_users?string[]

User IDs preselected on load, one chip each. Multi-select only.

Typestring[]

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.

Your AppAPP

A filter object restricts which conversation types Slack shows, and can drop bot users or external shared channels from the list:

Your AppAPP
PropType
initial_conversation?string

A conversation ID preselected on load. Slack documents that it takes precedence over default_to_current_conversation. Single-select only.

Typestring
initial_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.

Typestring[]
default_to_current_conversation?boolean

Preselects the conversation the surface was opened from, if any.

Typeboolean
Defaultfalse
filter?ConversationFilter

Narrows the list Slack offers. See below.

TypeConversationFilter

filter’s fields:

PropType
include?("im" | "mpim" | "private" | "public")[]

Only these conversation types are offered. Omit to allow all four.

Type("im" | "mpim" | "private" | "public")[]
exclude_bot_users?boolean

Drops bot users from the list.

Typeboolean
Defaultfalse
exclude_external_shared_channels?boolean

Drops Slack Connect (externally shared) channels from the list. Doesn't exclude external users from shared channels that remain.

Typeboolean
Defaultfalse

Channels 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

Channel

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:

Your AppAPP
PropType
initial_channel?string

A channel ID preselected on load. Single-select only.

Typestring
initial_channels?string[]

Channel IDs preselected on load. Multi-select only.

Typestring[]

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 input block it sends one only when the block sets dispatch_action: true. Otherwise its value waits in state until 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[] }[] };

Last updated on