> ## Documentation Index
> Fetch the complete documentation index at: https://developers.smarterservices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> BlockKit is a powerful system that allows you to build dynamic user interfaces using JSON structures. It provides a set of predefined elements that can be composed together to create rich, interactive experiences.

BlockKit elements are JSON objects that define the structure and behavior of UI components. Each element has a specific `type` property that identifies what kind of element it is, along with additional properties that configure its appearance and behavior.

## WYSIWYG Builder

The [BlockKit Builder](/platform/blockkit/builder) is a visual drag-and-drop editor for creating BlockKit layouts without writing JSON. It includes a block library, live canvas, properties panel, preview mode, and more.

## Available Elements

### Layout

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

### Content

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

### Lists

* [Bullet List](/platform/blockkit/bulletlist) - A block that displays an unordered (bullet) list
* [Ordered List](/platform/blockkit/orderedlist) - A block that displays a numbered (ordered) list
* [Step List](/platform/blockkit/steplist) - A block that displays a list of steps in a process or workflow
* [Step](/platform/blockkit/step) - A block that represents a step in a process or workflow
* [List Item](/platform/blockkit/listitem) - A list item that can be used in bullet or ordered lists

### Navigation

* [Wizard](/platform/blockkit/wizard) - A block that displays a multi-step wizard with navigation controls
* [Wizard Step](/platform/blockkit/wizardstep) - A block that represents a single step in a wizard

### Interactive

* [Button](/platform/blockkit/button) - An interactive button that triggers an action
* [Actions](/platform/blockkit/actions) - A container for a horizontal row of action buttons
* [Form](/platform/blockkit/form) - An interactive form with configurable fields that submits data to an endpoint

## Basic Structure

Every BlockKit element follows this basic structure:

```json theme={null}
{
  "type": "element-type",
  // Additional properties specific to the element type
}
```

## Interactive Components

BlockKit supports interactive elements that can POST data to server endpoints and receive new BlockKit content in response. This enables rich, dynamic experiences similar to Slack's Block Kit.

### 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

```json theme={null}
[
  {
    "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

| Type      | Description                                   |
| --------- | --------------------------------------------- |
| `replace` | Replace the triggering block with new content |
| `update`  | Update specific properties of the block       |
| `append`  | Append new blocks after the current block     |
| `errors`  | Display validation errors                     |

## 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](/platform/blockkit/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](/platform/blockkit/builder#visual-form-field-designer) instead of hand-writing JSON Schema for forms
* Use [Column Layouts](/platform/blockkit/columnlayout) to create responsive multi-column designs
* Use [Repeaters](/platform/blockkit/repeater) for data-driven lists — avoid duplicating blocks manually

## Composition

BlockKit elements can be nested to create complex structures:

* **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

Refer to individual element documentation for details on nesting rules and allowed children.