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 Messages Home tabs
Context	Modals Messages Home tabs
Divider	Modals Messages Home tabs
File	Messages
Header	Modals Messages Home tabs
Image	Modals Messages Home tabs
Input	Modals Messages Home tabs
Section	Modals Messages Home tabs
Video	Modals Messages Home tabs

Actions Block

Available in surfaces: Modals Messages Home tabs

A block that is used to hold interactive elements.

An action block containing multiple 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 25 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"
    }
  ]
}

View this block

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"
    }
  ]
}

View this block

Context Block

Available in surfaces: Modals Messages Home tabs

Displays message context, which can include both images and text.

An example of a context block

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**"
    }
  ]
}

View this block

Divider Block

Available in surfaces: Modals Messages 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.

An example of a divider block

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"
}

View this block

File Block

Appears in surfaces: Messages

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",
}

Available in surfaces: Modals Messages 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.

An example of a header block

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"
  }
}

View an example

Image Block

Available in surfaces: Modals Messages Home tabs

A simple image block, designed to make those cat photos really pop.

An example of an image block

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."
}

View this block

Input block

Available in surfaces: Modals Messages 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.

An example of an input block

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	A 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 or view and each iteration of a message or view. If a message or view 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 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
  }
}

View this block

Section Block

Available in surfaces: Modals Messages 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.

An example of a section block

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_."
  }
}

View this block

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"
    }
  ]
}

View this block

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"
    }
  }
}

View this block

Video Block

Available in surfaces: Modals Messages Home tabs

A video block is designed to embed videos in all app surfaces (e.g. link unfurls, messages, modals, App Home) — anywhere you can put blocks! To use the video block within your app, you must have the links.embed:write scope.

Requirements

Video blocks can only be posted by apps; users are not allowed to post embedded videos directly from Block Kit Builder.
Your app must have the the links.embed:write scope for both user and bot tokens.
video_url has to be included in the unfurl domains specified in your app.
video_url should be publicly accessible, unless the app relies on information received from the Events API payloads to make a decision on whether the viewer(s) of the content should have access. If so, the service could create a unique URL accessible only via Slack.
video_url must be compatible with an embeddable iFrame.
video_url must return a 2xx code OR 3xx with less than 5 redirects and an eventual 2xx.
video_url must not point to any Slack-related domain.

Constraints

Embeddable video players only (audio-only permitted)
Navigation, scrolling and overlays are not allowed within the iFrame.
Interactivity (e.g. likes, comments, and reactions) are allowed within your player but shouldn't completely overlay or navigate away from the content being embedded. These interactions will be anonymous since no user data is transferred to the embedded view.

An example of a video block for web

Fields

Property	Type	Required?	Description
`alt_text`	string	Yes	A tooltip for the video. Required for accessibility
`author_name`	string	No	Author name to be displayed. Must be less than 50 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`.
`description`	Object	Preferred	Description for video in plain text format.
`provider_icon_url`	string	No	Icon for the video provider - ex. Youtube icon
`provider_name`	string	No	The originating application or domain of the video ex. Youtube
`title`	Object	Yes	Video title in plain text format. Must be less than 200 characters.
`title_url`	string	Preferred	Hyperlink for the title text. Must correspond to the non-embeddable URL for the video. Must go to an HTTPS URL.
`thumbnail_url`	string	Yes	The thumbnail image URL
`video_url`	string	Yes	The URL to be embedded. Must match any existing unfurl domains within the app and point to a HTTPS URL.

The metadata received in the Block payload will be used to construct the description, provider, and title of the video in all clients. Developers have the flexibility to leave non-mandatory fields null and use other blocks to format this content.

Examples

An example video block payload:

{
	"blocks": [
		{
			"type": "section",
			"text": {
				"type": "plain_text",
				"text": "I think it's super cool",
				"emoji": true
			}
		},
		{
			"type": "video",
			"title": {
				"type": "plain_text",
				"text": "How to use Slack.",
				"emoji": true
			},
			"title_url": "https://www.youtube.com/watch?v=RRxQQxiM7AA",
			"description": {
				"type": "plain_text",
				"text": "Slack is a new way to communicate with your team. It's faster, better organized and more secure than email.",
				"emoji": true
			},
			"video_url": "https://www.youtube.com/embed/RRxQQxiM7AA?feature=oembed&autoplay=1",
			"alt_text": "How to use Slack?",
			"thumbnail_url": "https://i.ytimg.com/vi/RRxQQxiM7AA/hqdefault.jpg",
			"author_name": "Arcado Buendia",
			"provider_name": "YouTube",
			"provider_icon_url": "https://a.slack-edge.com/80588/img/unfurl_icons/youtube.png"
		}
	]
}

Reference: Layout blocks

Actions Block

Fields

Examples

Context Block

Fields

Example

Divider Block

Fields

Example

File Block

Fields

Example

Header Block

Fields

Examples

Image Block

Fields

Example

Input block

Fields

Example

Section Block

Fields

Examples

Video Block

Requirements

Constraints

Fields

Examples

Related content