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>

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

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

section

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

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

Two-column fields layout:

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

expand: true

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

divider

{ "type": "divider" }

context

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

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

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

Button styles:

primary

danger

primary

image

Standalone image with alt text. Provide either

image_url

slack_file

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

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

rich_text_list

style: "bullet"

"ordered"

indent

offset

border

rich_text_preformatted

rich_text_quote

Inline element types within sections:

text

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).

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

raw_text

rich_text

columns

invalid_attachments

markdown

Standard Markdown rendering for AI app output. Messages only.

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

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

input

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

label

plan

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

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

task_card

details

output

sources

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:

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

Text max 75 chars.

value

description

Confirmation Dialog

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

Anti-Patterns

text

text

chat.postMessage

text

blocks

text

invalid_attachments

mrkdwn

plain_text

plain_text

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

chat.postMessage

chat.update

views.open

views.update

views.push

trigger_id

views.publish

canvases.create

canvases.edit

lists.*

Modals collect input via

input

view_submission

private_metadata

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

slack#/entities/file

slack#/entities/task

slack#/entities/incident

slack#/entities/content_item

slack#/entities/item

Work Objects use

chat.unfurl

metadata

Reference Documentation

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