Go to Slack

Reference: Block elements

Block elements can be used inside of section, context, and actions layout blocks.

Our guide to composing rich message layouts shows you where and how to add blocks to messages.

Finally, the enabling interactivity guide will help you adjust your app to allow for the use of these interactive components.

The lists of fields and values below describe the JSON that apps can use to generate each element:


Image Element

An element to insert an image - this element can be used in section and context blocks only. If you want a block with only an image in it, you're looking for the image block.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always image.
image_url String Yes The URL of the image to be displayed.
alt_text String Yes A plain-text summary of the image. This should not contain any markup.

Example

{
  "type": "image",
  "image_url": "http://placekitten.com/700/500",
  "alt_text": "Multiple cute kittens"
}

View an example


Button Element

An interactive element that inserts a button. The button can be a trigger for anything from opening a simple link to starting a complex workflow.

To use interactive elements, you will need to make some changes to prepare your app. Read our guide to enabling interactivity.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always button.
text Object Yes A text object that defines the button's text. Can only be of type: plain_text. Maximum length for the text in this field is 75 characters.
action_id String Yes An identifier for this action. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
url String No A URL to load in the user's browser when the button is clicked. Maximum length for this field is 3000 characters. If you're using url, you'll still receive an interaction payload and will need to send an acknowledgement response.
value String No The value to send along with the interaction payload. Maximum length for this field is 2000 characters.
style String No Decorates buttons with alternative visual color schemes. Use this option with restraint.

primary gives buttons a green outline and text, ideal for affirmation or confirmation actions. primary should only be used for one button within a set.

danger gives buttons a red outline and text, and should be used when the action is destructive. Use danger even more sparingly than primary.

If you don't include this field, the default button style will be used.

Three buttons showing default, primary, and danger color styles

The image above shows the three different style options.
confirm Object No A confirm object that defines an optional confirmation dialog after the button is clicked.

Examples

A regular interactive button:

{
  "type": "button",
  "text": {
    "type": "plain_text",
    "text": "Click Me"
  },
  "value": "click_me_123",
  "action_id": "button"
}

A button with a primary style attribute:

{
  "type": "button",
  "text": {
    "type": "plain_text",
    "text": "Save"
  },
  "style": "primary",
  "value": "click_me_123",
  "action_id": "button"
}

A link button:

{
  "type": "button",
  "text": {
    "type": "plain_text",
    "text": "Link Button"
  },
  "url": "https://api.slack.com/block-kit"
}

View an example


Select Menu Elements

A select menu, just as with a standard HTML <select> tag, creates a drop down menu with a list of options for a user to choose. The select menu also includes type-ahead functionality, where a user can type a part or all of an option string to filter the list.

To use interactive elements, you will need to make some changes to prepare your app. Read our guide to enabling interactivity.

There are different types of select menu that depend on different data sources for their lists of options:


Select menu with static options

This is the simplest form of select menu, with a static list of options passed in when defining the element.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always static_select.
placeholder Object Yes 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.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
options Object[] Yes An array of option objects. Maximum number of options is 100. If option_groups is specified, this field should not be.
option_groups Object[] No An array of option group objects. Maximum number of option groups is 100. If options is specified, this field should not be.
initial_option Object No A single option that exactly matches one of the options within options or option_groups. This option will be selected when the menu initially loads.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A static select menu

[
    {
        "type": "section",
        "block_id": "section678",
        "text": {
            "type": "mrkdwn",
            "text": "Pick an item from the dropdown list"
        },
        "accessory": {
            "action_id": "text1234",
            "type": "static_select",
            "placeholder": {
                "type": "plain_text",
                "text": "Select an item"
            },
            "options": [
                {
                    "text": {
                        "type": "plain_text",
                        "text": "*this is plain_text text*"
                    },
                    "value": "value-0"
                },
                {
                    "text": {
                        "type": "plain_text",
                        "text": "*this is plain_text text*"
                    },
                    "value": "value-1"
                },
                {
                    "text": {
                        "type": "plain_text",
                        "text": "*this is plain_text text*"
                    },
                    "value": "value-2"
                }
            ]
        }
    }
]

Select menu with external data source

This select menu will load its options from an external data source, allowing for a dynamic list of options.

Setup

To use this menu type, you'll need to configure your app first:

  1. Goto your app's settings page and choose the Interactive Components feature menu.
  2. Add a URL to the Options Load URL under Message Menus.
  3. Save changes.

Each time a select menu of this type is opened or the user starts typing in the typeahead field, we'll send a request to your specified URL. Your app should return an HTTP 200 OK response, along with an application/json post body with an object containing either an options array, or an option_groups array. Here's an example response:

{
  "options": [
    {
      "text": {
        "type": "plain_text",
        "text": "*this is plain_text text*"
      },
      "value": "value-0"
    },
    {
      "text": {
        "type": "plain_text",
        "text": "*this is plain_text text*"
      },
      "value": "value-1"
    },
    {
      "text": {
        "type": "plain_text",
        "text": "*this is plain_text text*"
      },
      "value": "value-2"
    }
  ]
}

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always external_select.
placeholder Object Yes 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.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
initial_option Object No A single option that exactly matches one of the options within the options or option_groups loaded from the external data source. This option will be selected when the menu initially loads.
min_query_length Integer No When the typeahead field is used, a request will be sent on every character change. If you prefer fewer requests or more fully ideated queries, use the min_query_length attribute to tell Slack the fewest number of typed characters required before dispatch.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A select menu in a section block with an external data source:

[
    {
        "type": "section",
        "block_id": "section678",
        "text": {
            "type": "mrkdwn",
            "text": "Pick an item from the dropdown list"
        },
        "accessory": {
            "action_id": "text1234",
            "type": "external_select",
            "placeholder": {
                "type": "plain_text",
                "text": "Select an item"
      },
      "min_query_length": 3
        }
    }
]

Select menu with user list

This select menu will populate its options with a list of Slack users visible to the current user in the active workspace.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always users_select.
placeholder Object Yes 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.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
initial_user String No The user ID of any valid user to be pre-selected when the menu loads.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A select menu in a section block showing a list of users:

[
    {
        "type": "section",
        "block_id": "section678",
        "text": {
            "type": "mrkdwn",
            "text": "Pick a user from the dropdown list"
        },
        "accessory": {
            "action_id": "text1234",
            "type": "users_select",
            "placeholder": {
                "type": "plain_text",
                "text": "Select an item"
      }
        }
    }
]

Select menu with conversations list

This select menu will populate its options with a list of public and private channels, DMs, and MPIMs visible to the current user in the active workspace.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always conversations_select.
placeholder Object Yes 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.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
initial_conversation String No The ID of any valid conversation to be pre-selected when the menu loads.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A select menu in a section block showing a list of conversations:

[
    {
        "type": "section",
        "block_id": "section678",
        "text": {
            "type": "mrkdwn",
            "text": "Pick a conversation from the dropdown list"
        },
        "accessory": {
            "action_id": "text1234",
            "type": "conversations_select",
            "placeholder": {
                "type": "plain_text",
                "text": "Select an item"
      }
        }
    }
]

Select menu with channels list

This select menu will populate its options with a list of public channels visible to the current user in the active workspace.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always channels_select.
placeholder Object Yes 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.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
initial_channel String No The ID of any valid public channel to be pre-selected when the menu loads.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A select menu in a section block showing a list of channels:

[
    {
        "type": "section",
        "block_id": "section678",
        "text": {
            "type": "mrkdwn",
            "text": "Pick a channel from the dropdown list"
        },
        "accessory": {
            "action_id": "text1234",
            "type": "channels_select",
            "placeholder": {
                "type": "plain_text",
                "text": "Select an item"
      }
        }
    }
]

Overflow menu element

This is like a cross between a button and a select menu - when a user clicks on this overflow button, they will be presented with a list of options to choose from. Unlike the select menu, there is no typeahead field, and the button always appears with an ellipsis ("…") rather than customisable text.

As such, it is usually used if you want a more compact layout than a select menu, or to supply a list of less visually important actions after a row of buttons. You can also specify simple URL links as overflow menu options, instead of actions.

To use interactive elements like this, you will need to make some changes to prepare your app. Read our guide to enabling interactivity.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always overflow.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
options Object[] Yes An array of option objects to display in the menu. Maximum number of options is 5, minimum is 2.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a menu item is selected.

Example

A section block with an overflow menu:

{
  "type": "section",
  "block_id": "section 890",
  "text": {
    "type": "mrkdwn",
    "text": "This is a section block with an overflow menu."
  },
  "accessory": {
    "type": "overflow",
    "options": [
      {
        "text": {
          "type": "plain_text",
          "text": "*this is plain_text text*"
        },
        "value": "value-0"
      },
      {
        "text": {
          "type": "plain_text",
          "text": "*this is plain_text text*"
        },
        "value": "value-1"
      },
      {
        "text": {
          "type": "plain_text",
          "text": "*this is plain_text text*"
        },
        "value": "value-2"
      },
      {
        "text": {
          "type": "plain_text",
          "text": "*this is plain_text text*"
        },
        "value": "value-3"
      },
      {
        "text": {
          "type": "plain_text",
          "text": "*this is plain_text text*"
        },
        "value": "value-4"
      }
    ],
    "action_id": "overflow"
  }
}

View an example


Date picker element

An element which lets users easily select a date from a calendar style UI. Date picker elements can be used inside of section and actions blocks.

To use interactive elements like this, you will need to make some changes to prepare your app. Read our guide to enabling interactivity.

Fields

Field Type Required? Description
type String Yes The type of element. In this case type is always datepicker.
action_id String Yes An identifier for the action triggered when a menu option is selected. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other action_ids used elsewhere by your app. Maximum length for this field is 255 characters.
placeholder Object No A plain_text only text object that defines the placeholder text shown on the datepicker. Maximum length for the text in this field is 150 characters.
initial_date String No The initial date that is selected when the element is loaded. This should be in the format YYYY-MM-DD.
confirm Object No A confirm object that defines an optional confirmation dialog that appears after a date is selected.

Example

A section block containing a datepicker element:

{
  "type": "section",
  "block_id": "section1234",
  "text": {
    "type": "mrkdwn",
    "text": "Pick a date for the deadline."
  },
  "accessory": {
    "type": "datepicker",
    "action_id": "datepicker123",
    "initial_date": "1990-04-28",
    "placeholder": {
      "type": "plain_text",
      "text": "Select a date"
    }
  }
}

View an example