Block Kit
The Block Kit UI framework is built with blocks, block elements and composition objects.
Blocks are visual components that can be arranged to create app layouts. Apps can add blocks to surfaces such as the Home tab, messages and modals. You can include up to 50 blocks in each message, and 100 blocks in modals or Home tabs.
Blocks may also contain block elements. Block elements are usually interactive components, such as buttons and menus.
Blocks and block elements are built with composition objects. Composition objects define text, options, or other interactive features within certain blocks and block elements.
Whether you're composing layouts for modals, messages, or Home tabs, the Block Kit building experience is the same in that your app will be sculpting specially-structured JSON to express itself. The result is clear, interactive communication between your app and its users.
Read on to learn how you can construct the stacks of blocks that app surfaces love to consume.
Eager to see Block Kit in action? Take a peek in Block Kit Builder.
Block Kit and AI
Agents and AI-powered apps have unique UI needs. Block Kit provides blocks suited for agent-driven experiences, including real-time updates, rich content generation, and interactive workflows.
Agent features
Agents can use Block Kit within features designed for agent-driven experiences:
Slack Code
Code channels are dedicated channels for agent-user collaboration. They feature:
- Context bar: Display agent-supplied items like repository, branch, PR status
- View tabs: Attach diffs, HTML, Block Kit, or canvases as tabs
- Streaming messages: Real-time updates as agents process
Use Block Kit blocks within code channel messages and view tabs to present agent work and results.
Agent sessions
Agent sessions are thread-based conversations with status indicators. Sessions provide:
- Status indicators: Show "processing", "active", "suspended", or "closed" states
- Stop buttons: Allow users to interrupt agent work
- Streaming support: Real-time message updates
Use Block Kit blocks in streaming messages within agent sessions to display agent output and progress.
Streaming messages
The chat.startStream API method enables real-time message updates. Agents can:
- Start a stream with initial content
- Update the stream as processing continues
- Stop the stream and present final results
Combine streaming with Block Kit blocks to create dynamic, real-time agent experiences.
Best practices for Block Kit and AI
- Use rich text for formatted output. When displaying agent-generated content, prefer rich text blocks over markdown for better formatting control and consistency.
- Organize with containers. Use container blocks to group related information and improve visual hierarchy in complex agent layouts.
- Highlight important information. Use alert blocks to draw attention to warnings, errors, or critical information from agent analysis.
- Present multiple results with carousels. When agents generate multiple results or options, use carousel blocks to allow users to browse through them easily.
- Visualize data. Use data visualization blocks to display charts, graphs, and statistical data from agent analysis in visual format.
- Make results actionable. Use task card blocks to present agent-generated action items and next steps with clear call-to-action buttons.
- Stream long-running operations. For agents that take time to process, use streaming messages with Block Kit to show progress and intermediate results in real-time.
Learn more about building agents in the developing an agent guide.
Placing blocks within surfaces
Blocks are used within all app surfaces: Home tabs, messages and modals can all be designed using blocks.
Each of them uses a blocks array that you prepare by stacking individual blocks together.
Check out app surfaces to learn more about using these different surfaces, and how to add blocks to your app's Home tab, messages, and modals.
Read the Block Kit reference guides to check if a block is compatible with your app's surfaces.
Building blocks
There's no special setup needed to start using blocks in app surfaces. However, just as when you open a pack of generic, colorful, interlocking plastic bricks, you should read the instructions first.
Defining a single block
Each block is represented in our APIs as a JSON object. Here's an example of a section block:
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "New Paid Time Off request from <example.com|Ayda Mensah>\n\n<https://example.com|View request>"
}
}
Every block contains a type field, specifying which of the available blocks to use along with other fields that describe the content of the block.
Block Kit Builder is a visual prototyping sandbox that will let you choose from, configure, and preview all the available blocks.
If you want to skip the builder, the block reference guide contains the specifications of every block, and the JSON fields required for each of them.
Stacking multiple blocks
Individual blocks can be stacked together to create complex visual layouts.
When you've chosen each of the blocks you want in your layout, place each of them in an array, in visual order, like this:
[
{
"type": "header",
"text": {
"type": "plain_text",
"text": "New request"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Type:*\nPaid Time Off"
},
{
"type": "mrkdwn",
"text": "*Created by:*\n<example.com|Ayda Mensah>"
}
]
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*When:*\nAug 10 - Aug 13"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "<https://example.com|View request>"
}
}
]
Block Kit Builder will allow you to drag, drop, and rearrange blocks to design and preview Block Kit layouts.
Alternatively you can use the block reference guide to manually generate a complete blocks array, like the one shown above.
Your newly created array of blocks can be used with a range of different app surfaces.
Accessibility considerations
When posting messages, it is expected behavior that screen readers will default to the top-level text field of the post, and will not read the content of any interior blocks in the underlying structure of the message. Therefore, to make an accessible app, you must either:
- include all necessary content for screen reader users in the top-level
textfield of your message, or - do not include a top-level
textfield if the message hasblocks, and allow Slack attempt to build it for you by appending content from supportedblocksto be read by the screen reader.
Adding interactivity to blocks with block elements
Blocks can be made to interact with users via Block Kit elements. Elements include interactive components such as buttons, menus and text inputs.
Here's an example of a button element within a section block.
{
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "This is a section block with a button."
},
"accessory": {
"type": "button",
"text": {
"type": "plain_text",
"text": "Click Me",
"emoji": true
},
"value": "click_me_123",
"action_id": "button-action"
}
}
]
}
When you add an interactive component to a surface in your Slack app, you've opened the door to user interaction. People will push your app's buttons and expecting a helpful and prompt reaction.
Apps need to handle the requests that start to flow their way, and respond appropriately. Follow our guide to handling user interaction to prepare your app for the interactivity that Block Kit will inspire.
Block Kit builder allows you to add elements to blocks as well. Give it a try! Alternatively, read the Block Kit element reference guide for all the info you'll need for manually implementing individual elements.
Next steps
Check out the following guides for everything blocks: