Reference: Layout blocks
Blocks are a series of components that can be combined to create visually rich and compellingly interactive messages.
Read our guide to building block layouts to learn where and how to use each of these components. You can include up to 50 blocks in each message, and 100 blocks in modals or home tabs.
The lists of fields and values below describe the JSON that apps can use to generate each block:
| Block type | Available in surfaces |
|---|---|
| Actions | Modals Home tabs |
| Context | Modals Home tabs |
| Divider | Modals Home tabs |
| File | |
| Header | Modals Home tabs |
| Image | Modals Home tabs |
| Input | Modals Home tabs |
| Section | Modals Home tabs |
Actions Block
Available in surfaces: Modals Home tabs
A block that is used to hold interactive elements.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For an actions block, type is always actions. |
elements |
Object[] | Yes | An array of interactive element objects - buttons, select menus, overflow menus, or date pickers. There is a maximum of 5 elements in each action block. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, a block_id will be generated. You can use this block_id when you receive an interaction payload to identify the source of the action. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Examples
An actions block with a select menu and a button:
{
"type": "actions",
"block_id": "actions1",
"elements": [
{
"type": "static_select",
"placeholder":{
"type": "plain_text",
"text": "Which witch is the witchiest witch?"
},
"action_id": "select_2",
"options": [
{
"text": {
"type": "plain_text",
"text": "Matilda"
},
"value": "matilda"
},
{
"text": {
"type": "plain_text",
"text": "Glinda"
},
"value": "glinda"
},
{
"text": {
"type": "plain_text",
"text": "Granny Weatherwax"
},
"value": "grannyWeatherwax"
},
{
"text": {
"type": "plain_text",
"text": "Hermione"
},
"value": "hermione"
}
]
},
{
"type": "button",
"text": {
"type": "plain_text",
"text": "Cancel"
},
"value": "cancel",
"action_id": "button_1"
}
]
}
An actions block with a datepicker, an overflow, and a button:
{
"type": "actions",
"block_id": "actionblock789",
"elements": [
{
"type": "datepicker",
"action_id": "datepicker123",
"initial_date": "1990-04-28",
"placeholder": {
"type": "plain_text",
"text": "Select a date"
}
},
{
"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"
},
{
"type": "button",
"text": {
"type": "plain_text",
"text": "Click Me"
},
"value": "click_me_123",
"action_id": "button"
}
]
}
Context Block
Available in surfaces: Modals Home tabs
Displays message context, which can include both images and text.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For a context block, type is always context. |
elements |
Object[] | Yes | An array of image elements and text objects. Maximum number of items is 10. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Example
{
"type": "context",
"elements": [
{
"type": "image",
"image_url": "https://image.freepik.com/free-photo/red-drawing-pin_1156-445.jpg",
"alt_text": "images"
},
{
"type": "mrkdwn",
"text": "Location: **Dogpatch**"
}
]
}
Divider Block
Available in surfaces: Modals Home tabs
A content divider, like an <hr>, to split up different blocks inside of a message. The divider block is nice and neat, requiring only a type.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For a divider block, type is always divider. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Example
{
"type": "divider"
}
File Block
Appears in surfaces:
Displays a remote file. You can't add this block to app surfaces directly, but it will show up when retrieving messages that contain remote files.
If you want to add remote files to messages, follow our guide.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For a file block, type is always file. |
external_id |
String | Yes | The external unique ID for this file. |
source |
String | Yes | At the moment, source will always be remote for a remote file. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Example
{
"type": "file",
"external_id": "ABCD1",
"source": "remote",
}
Header Block
Available in surfaces: Modals Home tabs
A header is a plain-text block that displays in a larger, bold font. Use it to delineate between different groups of content in your app's surfaces.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For this block, type will always be header. |
text |
Object | Yes | The text for the block, in the form of a plain_text text object. Maximum length for the text in this field is 150 characters. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Examples
A header block:
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Budget Performance"
}
}
Image Block
Available in surfaces: Modals Home tabs
A simple image block, designed to make those cat photos really pop.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For an image block, type is always image. |
image_url |
String | Yes | The URL of the image to be displayed. Maximum length for this field is 3000 characters. |
alt_text |
String | Yes | A plain-text summary of the image. This should not contain any markup. Maximum length for this field is 2000 characters. |
title |
Object | No | An optional title for the image in the form of a text object that can only be of type: plain_text. Maximum length for the text in this field is 2000 characters. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
Example
{
"type": "image",
"title": {
"type": "plain_text",
"text": "Please enjoy this photo of a kitten"
},
"block_id": "image4",
"image_url": "http://placekitten.com/500/500",
"alt_text": "An incredibly cute kitten."
}
Input block
Available in surfaces: Modals Home tabs
A block that collects information from users - it can hold a plain-text input element, a checkbox element, a radio button element, a select menu element, a multi-select menu element, or a datepicker.
Read our guides to collecting input in modals or in Home tabs to learn how input blocks pass information to your app.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For an input block, type is always input. |
label |
Object | Yes | A label that appears above an input element in the form of a text object that must have type of plain_text. Maximum length for the text in this field is 2000 characters. |
element |
Object | Yes | An plain-text input element, a checkbox element, a radio button element, a select menu element, a multi-select menu element, or a datepicker. |
dispatch_action |
Boolean | No | A boolean that indicates whether or not the use of elements in this block should dispatch a block_actions payload. Defaults to false. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
hint |
Object | No | An optional hint that appears below an input element in a lighter grey. It must be a a text object with a type of plain_text. Maximum length for the text in this field is 2000 characters. |
optional |
Boolean | No | A boolean that indicates whether the input element may be empty when a user submits the modal. Defaults to false. |
Example
An input block containing a plain-text input element.
{
"type": "input",
"element": {
"type": "plain_text_input"
},
"label": {
"type": "plain_text",
"text": "Label",
"emoji": true
}
}
Section Block
Available in surfaces: Modals Home tabs
A section is one of the most flexible blocks available - it can be used as a simple text block, in combination with text fields, or side-by-side with any of the available block elements.
Fields
| Field | Type | Required? | Description |
|---|---|---|---|
type |
String | Yes | The type of block. For a section block, type will always be section. |
text |
Object | Preferred | The text for the block, in the form of a text object. Maximum length for the text in this field is 3000 characters. This field is not required if a valid array of fields objects is provided instead. |
block_id |
String | No | A string acting as a unique identifier for a block. If not specified, one will be generated. You can use this block_id when you receive an interaction payload to identify the source of the action. Maximum length for this field is 255 characters. block_id should be unique for each message and each iteration of a message. If a message is updated, use a new block_id. |
fields |
Object[] | Maybe | Required if no text is provided. An array of text objects. Any text objects included with fields will be rendered in a compact format that allows for 2 columns of side-by-side text. Maximum number of items is 10. Maximum length for the text in each item is 2000 characters. Click here for an example. |
accessory |
Object | No | One of the available element objects. |
Examples
A simple text section block:
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "A message *with some bold text* and _some italicized text_."
}
}
A section block containing text fields:
{
"type": "section",
"text": {
"text": "A message *with some bold text* and _some italicized text_.",
"type": "mrkdwn"
},
"fields": [
{
"type": "mrkdwn",
"text": "High"
},
{
"type": "plain_text",
"emoji": true,
"text": "String"
}
]
}
A section block containing a datepicker element:
{
"type": "section",
"text": {
"text": "*Sally* has requested you set the deadline for the Nano launch project",
"type": "mrkdwn"
},
"accessory": {
"type": "datepicker",
"action_id": "datepicker123",
"initial_date": "1990-04-28",
"placeholder": {
"type": "plain_text",
"text": "Select a date"
}
}
}