Overview

​

WYSIWYG Builder

​

Available Elements

​

Layout

• Section - A container block that groups other block elements together
• Column Layout - Arrange content in configurable column layouts (50/50, 66/33, 75/25, etc.)
• Repeater - Repeat template content for each item in an array
• Remote Block - Load and render BlockKit content from a remote URL

​

Content

• Heading - A block that displays a heading with a specified level
• Text - A block that displays formatted text with optional replacements
• Alert - A block that displays an alert message with different severity levels
• Callout - A block that displays a callout with an icon, title, and content
• Icon - A block that displays an icon with optional color and alignment
• Block Replacement - A block that serves as a placeholder for dynamic content

​

Lists

• Bullet List - A block that displays an unordered (bullet) list
• Ordered List - A block that displays a numbered (ordered) list
• Step List - A block that displays a list of steps in a process or workflow
• Step - A block that represents a step in a process or workflow
• List Item - A list item that can be used in bullet or ordered lists

​

Navigation

• Wizard - A block that displays a multi-step wizard with navigation controls
• Wizard Step - A block that represents a single step in a wizard

​

Interactive

• Button - An interactive button that triggers an action
• Actions - A container for a horizontal row of action buttons
• Form - An interactive form with configurable fields that submits data to an endpoint

​

Basic Structure

{
  "type": "element-type",
  // Additional properties specific to the element type
}

​

Interactive Components

​

How It Works

1. Interactive elements (buttons, forms) live inside actions or form blocks
2. Each element has an action_id and the container has an action_url
3. User interaction triggers an HTTP POST to the endpoint with a structured payload
4. The server responds with new BlockKit JSON to replace, update, or append blocks

[
  {
    "type": "actions",
    "action_url": "https://api.example.com/handle",
    "elements": [
      {
        "type": "button",
        "text": "Approve",
        "action_id": "approve",
        "style": "primary"
      },
      {
        "type": "button",
        "text": "Reject",
        "action_id": "reject",
        "style": "danger"
      }
    ]
  }
]

​

Server Response Types

​

Getting Started

1. Choose the appropriate element type for your needs
2. Review the element’s documentation for required and optional properties
3. Compose your JSON structure using the element’s schema
4. Test your BlockKit structure using the WYSIWYG Builder

​

Best Practices

• Always include required properties for each element
• Use meaningful text content that provides value to users
• Consider accessibility when composing your BlockKit structures
• Test your structures with different data to ensure they work as expected
• Use the visual form designer instead of hand-writing JSON Schema for forms
• Use Column Layouts to create responsive multi-column designs
• Use Repeaters for data-driven lists — avoid duplicating blocks manually

​

Composition

• Sections can contain headings, text, alerts, lists, actions, forms, and column layouts
• Wizards contain wizard steps, each of which can hold any content blocks
• Column Layouts divide content into side-by-side columns
• Actions contain buttons arranged in a horizontal row
• Lists contain list items