Slack Block Kit

UI framework for building rich, interactive layouts in Slack messages, modals, and App Home.

CRITICAL: Two Markup Systems

Text inside Block Kit text objects uses Slack mrkdwn syntax (

*bold*

<url|text>

), NOT standard Markdown. The only exception is the

markdown

block which uses standard Markdown.

Quick Decision Trees

"Should I use blocks?"

Response type?
├─ Conversational reply, short answer, <3 lines   → text only (no blocks)
├─ Multi-section summary, report, dashboard        → blocks
├─ Two-column key-value data                       → blocks (section fields)
├─ Tabular data                                    → blocks (table)
├─ Code with heading or surrounding context         → blocks
├─ Visual separation needed between topics          → blocks
└─ Feedback buttons or interactive elements         → blocks

"Which block type?"

What am I rendering?
├─ Large section title                → header (plain_text, 150 chars max)
├─ Body text or key-value pairs       → section (text + fields + accessory)
├─ Small metadata or secondary info   → context (images + text, 10 max)
├─ Horizontal separator               → divider
├─ Buttons, menus, date pickers       → actions (25 elements max)
├─ Standalone image                   → image (image_url or slack_file)
├─ Formatted text with lists, quotes  → rich_text (nested sub-elements)
├─ Tabular data                       → table (100 rows, 20 cols, 1 per msg)
├─ LLM-generated markdown content     → markdown (standard MD, messages only)
├─ Embedded video player              → video (requires links.embed:write)
├─ Remote file reference              → file (read-only, source: "remote")
├─ Feedback thumbs up/down            → context_actions (messages only)
├─ Collecting user input (modals)     → input (label + element)
├─ AI agent task steps                → plan (sequential tasks, messages only)
└─ Single task with status            → task_card (inside plan or standalone)

"mrkdwn or markdown block?"

Content source?
├─ Short formatted text, labels, fields     → mrkdwn in section/context
├─ Long-form LLM-generated content          → markdown block (standard MD)
├─ Need tables inside blocks                → mrkdwn in section (manual layout)
├─ Need headings                            → markdown block or header blocks
└─ Mixed: structured layout + prose         → section/header blocks + markdown block

Block Types Overview

header

Large bold text for section titles.

plain_text

only. Max 150 chars.

json

{ "type": "header", "text": { "type": "plain_text", "text": "Section Title", "emoji": true } }

section

Primary content block. Supports text, two-column fields, and one accessory element.

json

{
  "type": "section",
  "text": { "type": "mrkdwn", "text": "*Project Status*\nAll systems operational." }
}

Two-column fields layout:

json

{
  "type": "section",
  "fields": [
    { "type": "mrkdwn", "text": "*Status:*\nActive" },
    { "type": "mrkdwn", "text": "*Owner:*\nChris" },
    { "type": "mrkdwn", "text": "*Priority:*\nHigh" },
    { "type": "mrkdwn", "text": "*Due:*\nFriday" }
  ]
}

Either

text

fields

required (or both). Text max 3000 chars. Fields max 10 items, each max 2000 chars. Set

expand: true

to force full text display without "see more" truncation.

Compatible accessories: button, overflow, datepicker, timepicker, select menus, multi-select menus, checkboxes, radio buttons, image.

divider

json

{ "type": "divider" }

context

Small, muted text for metadata. Elements: mrkdwn text objects or image elements. Max 10 elements.

json

{
  "type": "context",
  "elements": [
    { "type": "mrkdwn", "text": "Last updated: Feb 9, 2026" },
    { "type": "mrkdwn", "text": "Source: deploy-bot" }
  ]
}

actions

Interactive elements: buttons, select menus, overflow menus, date pickers. Max 25 elements.

json

{
  "type": "actions",
  "elements": [
    {
      "type": "button",
      "text": { "type": "plain_text", "text": "Approve", "emoji": true },
      "style": "primary",
      "action_id": "approve_action",
      "value": "approved"
    }
  ]
}

Button styles:

primary

(green),

danger

(red), or omit for default. Use

primary

sparingly — one per set. Action IDs must be unique within the message.

image

Standalone image with alt text. Provide either

image_url

(public, max 3000 chars) or

slack_file

object. Formats: png, jpg, jpeg, gif.

json

{
  "type": "image",
  "image_url": "https://example.com/chart.png",
  "alt_text": "Deployment success rate chart",
  "title": { "type": "plain_text", "text": "Deploy Metrics" }
}

rich_text

Advanced formatted text with nested elements. Supports styled text, lists, code blocks, and quotes. See references/RICH-TEXT.md for deep dive.

json

{
  "type": "rich_text",
  "elements": [
    {
      "type": "rich_text_section",
      "elements": [
        { "type": "text", "text": "Key findings:", "style": { "bold": true } }
      ]
    },
    {
      "type": "rich_text_list",
      "style": "bullet",
      "elements": [
        { "type": "rich_text_section", "elements": [{ "type": "text", "text": "Latency reduced by 40%" }] },
        { "type": "rich_text_section", "elements": [{ "type": "text", "text": "Error rate under 0.1%" }] }
      ]
    }
  ]
}

Sub-element types:

rich_text_section

(paragraph),

rich_text_list

(

style: "bullet"

"ordered"

, with

indent

offset

border

rich_text_preformatted

(code block),

rich_text_quote

(blockquote).

Inline element types within sections:

text

(with optional

style: { bold, italic, strike, code, underline }

link

emoji

user

channel

usergroup

broadcast

date

color

table

Tabular data. One table per message (appended as attachment at bottom).

json

{
  "type": "table",
  "rows": [
    [
      { "type": "raw_text", "text": "Service" },
      { "type": "raw_text", "text": "Status" },
      { "type": "raw_text", "text": "Latency" }
    ],
    [
      { "type": "raw_text", "text": "API" },
      { "type": "raw_text", "text": "Healthy" },
      { "type": "raw_text", "text": "12ms" }
    ]
  ],
  "column_settings": [
    { "align": "left" },
    { "align": "center" },
    { "align": "right" }
  ]
}

Each row is an array of cell objects (NOT an object with a

cells

property). Cell types:

raw_text

rich_text

. There is no

columns

property — the first row is the header. Max 100 rows, 20 columns. Multiple tables trigger

invalid_attachments

error.

markdown

Standard Markdown rendering for AI app output. Messages only.

json

{ "type": "markdown", "text": "**Bold**, *italic*, [link](https://example.com)\n\n## Heading\n\n- List item" }

Supports: bold, italic, strikethrough, links, headers, ordered/unordered lists, inline code, code blocks, block quotes. Does NOT support: syntax highlighting, horizontal rules, tables, task lists. Cumulative 12,000 char limit per payload.

block_id

is ignored.

context_actions

Feedback and icon buttons for message-level actions. Messages only. Max 5 elements. Compatible elements:

feedback_buttons

icon_button

video

Embedded video player. Requires

links.embed:write

scope, publicly accessible URL in app's unfurl domains.

input

Collects user data in modals, messages, and Home tabs. Requires

label

(plain_text, 2000 chars) and one compatible element. See references/ELEMENTS.md for all input element types.

plan

Container for sequential task cards, designed for AI agent output. Messages only.

json

{
  "type": "plan",
  "title": "Thinking completed",
  "tasks": [
    { "task_id": "t1", "title": "Fetched data", "status": "complete" },
    { "task_id": "t2", "title": "Generating report", "status": "in_progress" }
  ]
}

Task status values:

pending

in_progress

complete

error

. Each task is a

task_card

block with optional

details

output

(rich_text), and

sources

(url elements).

file

Remote file reference. Read-only. Cannot be directly added to messages by apps.

Composition Objects

Option Object

Used in select menus, overflow, checkboxes, radio buttons:

json

{
  "text": { "type": "plain_text", "text": "Option 1" },
  "value": "opt_1",
  "description": { "type": "plain_text", "text": "Detailed description" }
}

Text max 75 chars.

value

max 150 chars.

description

optional, max 75 chars.

Confirmation Dialog

json

{
  "title": { "type": "plain_text", "text": "Are you sure?" },
  "text": { "type": "plain_text", "text": "This action cannot be undone." },
  "confirm": { "type": "plain_text", "text": "Yes, do it" },
  "deny": { "type": "plain_text", "text": "Cancel" },
  "style": "danger"
}

Conversation Filter

Filters conversation select menus.

include

im

mpim

private

public

Dispatch Action Configuration

Controls when input elements trigger

block_actions

on_enter_pressed

on_character_entered

See references/COMPOSITION.md for full property tables.

Limits

Constraint	Limit
Blocks per message	50
Blocks per modal/Home tab	100
Section text	3000 chars
Section fields	10 items, 2000 chars each
Header text	150 chars
Context elements	10
Actions elements	25
Context actions elements	5
Table rows	100
Table columns	20
Tables per message	1
Markdown block text	12,000 chars cumulative per payload
Modal title	24 chars
Modal submit/close text	24 chars
Modal views in stack	3
Modal private_metadata	3000 chars
Button text	75 chars (displays ~30)
Button value	2000 chars
action_id / block_id	255 chars
Overflow options	5
Select options	100
Option text	75 chars
Placeholder text	150 chars
File input max file size	10MB per file

Anti-Patterns

Anti-Pattern	Problem	Fix
Blocks without `text` fallback	Empty notifications, no accessibility fallback	Always provide `text` in `chat.postMessage`
`text` and `blocks` diverge	Confusing: notification says one thing, chat shows another	Keep semantically aligned
Blocks for simple replies	Visual noise for short responses	Use `text` only for simple replies
2+ tables in one message	`invalid_attachments` error	One table per message
`mrkdwn` in header text	Ignored — headers only accept `plain_text`	Use `plain_text` type
Long header text	Silently truncated at 150 chars	Keep under 150
Missing `alt_text` on images	Accessibility failure, API may reject	Always include alt_text

Best Practices

Use blocks when:

The response has multiple distinct sections (summaries, reports, dashboards)
Two-column key-value layouts improve readability (metadata, config summaries)
A table presents data more clearly than prose
Visual separation between topics helps comprehension
Code needs a header or surrounding context
Interactive elements (buttons, menus, feedback) are needed

Don't use blocks when:

The response is conversational ("sure, done", "hey, good morning")
The response is under ~3 lines of text
The content is a simple answer to a direct question

Always:

Provide a complete
```
text
```
field as the accessible fallback (notifications, threads, search, screen readers)
Keep the
```
text
```
and
```
blocks
```
semantically aligned
Use mrkdwn syntax in text objects, not standard Markdown (except in
```
markdown
```
blocks)
Escape
```
&
```
,
```
<
```
,
```
>
```
in user-generated content

Surfaces Overview

Surface	Max Blocks	Key Methods	Notes
Messages	50	`chat.postMessage` , `chat.update`	Primary output surface
Modals	100	`views.open` , `views.update` , `views.push`	Requires `trigger_id` (3s expiry), up to 3 stacked views
App Home	100	`views.publish`	Private per-user view, Home/Messages/About tabs
Canvases	N/A	`canvases.create` , `canvases.edit`	Markdown only — no Block Kit support
Lists	N/A	`lists.*` API methods	Task tracking and project management
Split View	N/A	Agents & AI Apps config	AI chat surface with Chat + History tabs

Modals collect input via

input

blocks, return

view_submission

payloads. They chain up to 3 views with push/update/clear response actions.

private_metadata

(3000 chars) persists context between views.

Work Objects

Work Objects render rich entity previews when links are shared in Slack. They extend link unfurling with structured data, flexpane details, editable fields, and actions.

Entity Types

Type	Entity ID	Purpose
File	`slack#/entities/file`	Documents, spreadsheets, images
Task	`slack#/entities/task`	Tickets, to-dos, work items
Incident	`slack#/entities/incident`	Service interruptions, outages
Content Item	`slack#/entities/content_item`	Articles, pages, wiki entries
Item	`slack#/entities/item`	General-purpose entity

Work Objects use

chat.unfurl

with a

metadata

parameter containing entity type, external reference, and entity payload. See references/WORK-OBJECTS.md for full implementation details.

Reference Documentation

File	Purpose
references/CHEATSHEET.md	Quick reference: all blocks, elements, limits at a glance
references/BLOCKS.md	All 15 block types with full property tables and constraints
references/ELEMENTS.md	All 20 interactive elements with properties and constraints
references/COMPOSITION.md	Composition objects: text, option, confirmation, filters
references/RICH-TEXT.md	Rich text block deep dive: sub-elements, inline types, styles
references/SURFACES.md	Modals, App Home, canvases, lists, split view
references/WORK-OBJECTS.md	Entity types, chat.unfurl, flexpane, editable fields, actions

Sources

Block Kit Reference — Slack
Block Kit Blocks — Slack
Block Kit Elements — Slack
Block Kit Composition Objects — Slack
Work Objects — Slack
Surfaces — Slack
Modals — Slack
App Home — Slack
Canvases — Slack
Lists — Slack
Split View — Slack
App Design — Slack

slack-block-kit

NPX Install

Tags

SKILL.md Content

Slack Block Kit

CRITICAL: Two Markup Systems

Quick Decision Trees

"Should I use blocks?"

"Which block type?"

"mrkdwn or markdown block?"

Block Types Overview

header

section

divider

context

actions

image

rich_text

table

markdown

context_actions

video

input

plan

file

Composition Objects

Option Object

Confirmation Dialog

Conversation Filter

Dispatch Action Configuration

Limits

Anti-Patterns

Best Practices

Surfaces Overview

Work Objects

Entity Types

Reference Documentation

Sources