Welcome to slackblocks!
slackblocks builds Slack messages with the Block Kit API in Python, TypeScript, Go, Java, C#, and Ruby — without writing JSON by hand.
It exists because Block Kit JSON is verbose, easy to get subtly wrong, and unpleasant to maintain in source control. slackblocks gives you:
- Typed, idiomatic APIs for Python, TypeScript, Go, Java, C#, and Ruby.
- Validation as you build — character limits, required fields, mutually-exclusive options, and element-type restrictions are enforced at construction time, so you find out before hitting Slack's API.
- Drop-in compatibility with established Slack SDKs and clients and their plain JSON payloads.
- A small runtime footprint. Python has no runtime dependencies, TypeScript emits a self-contained ESM module, Go integrates with
slack-go/slack, Java implements the official Slack SDK block interfaces, C# depends on nothing beyond .NET, and Ruby uses the defaultjsongem.
Quick Start
Ready to build your first message? The Quick Start guide takes you from installation to a validated Slack payload using the language selected in the top navigation.
Components
The Slack Block Kit API defines several resource types (all defined in JSON) that work together to build block-based messages.
The Python package mirrors that hierarchy with classes.
Objects
Objects (e.g. Text, Option, Confirm) are the lowest-level primitives — small composable pieces that populate Elements and Blocks.
For convenience, PlainText and Markdown are thin subclasses of Text that you can use anywhere a Text is expected — PlainText("Hi", emoji=True) reads more naturally than Text("Hi", type_=TextType.PLAINTEXT, emoji=True).
Elements
Elements are typically interactive UI controls that go inside blocks. The CheckboxGroup element, for instance, takes one or more Option items and presents a checkbox menu.
Blocks
Blocks are the core visual unit of a message. Different block classes produce different UI:
SectionBlock— a chunk of markdown text, optionally with an accessory element.HeaderBlock— a large bold title.DividerBlock— a visual separator (like an HTML<hr>).MarkdownBlock— GitHub-flavored Markdown (Slack 2024+; richer formatting thanmrkdwn).RichTextBlock— formatted text with inline styling, lists, code blocks, and quotes.ActionsBlock— a row of interactive elements like buttons or menus.AlertBlock— a severity-labelled notice for a modal.CardBlockandCarouselBlock— compact linked content, individually or in a scrolling collection.ContainerBlock— a titled group of related child blocks.ContextActionsBlock— feedback and icon controls beside contextual content.DataTableBlockandDataVisualizationBlock— structured data as a table or chart.PlanBlockandTaskCardBlock— plans, task state, rich output, and sources.VideoBlock— embed a video from a Slack-supported provider.ImageBlock,ContextBlock,InputBlock,FileBlock,TableBlock.
See Using Blocks for examples of all block types side-by-side with their JSON output and Slack rendering.
Messages
Messages are a convenience wrapper around blocks that can be unpacked directly into the Slack SDK's chat_postMessage (and friends).
Message— a normal channel message.WebhookMessage— for incoming webhooks.MessageResponse— replies to slash commands and interactions.
Views
Views are an alternative usage of blocks that build custom UI surfaces in Slack — modal dialogs and the App Home tab — typically used by interactive Slack apps.
Utilities
block_kit_builder_url(payload, team_id=None)— turn any block, list of blocks, message, or view into a Block Kit Builder URL for browser-based preview.Block.from_dict(data)— parse a Slack-shaped block payload back into aslackblocksobject. Per-classfrom_dictparsers are also available on every composition object.
The TypeScript package exposes chainable PascalCase builders that produce typed,
Slack-shaped objects when .build() is called.
Composition objects
Builders such as PlainText, Markdown, and Option create the small values used throughout Block Kit payloads.
Elements
Interactive controls are built with Button, Checkboxes, StaticSelect, and DatePicker.
Blocks
Every block builder follows the same <Kind>Block naming pattern. Alongside SectionBlock, ActionsBlock, and VideoBlock, the API includes AlertBlock, CardBlock, CarouselBlock, ContainerBlock, ContextActionsBlock, DataTableBlock, DataVisualizationBlock, PlanBlock, and TaskCardBlock.
Payloads
Use Message, WebhookMessage, and MessageResponse for message payloads. Use Modal and HomeTab for Slack views.
Higher-level components
Paginator renders a selected page
with previous and next controls. Accordion
groups Slack-native collapsible sections. Both expand directly inside .blocks().
Utilities
blockKitBuilderUrlcreates a browser preview URL.validateandassertValidvalidate existing Slack-shaped data.
The Go module exposes New… constructors whose fluent methods materialise ordinary
map[string]any-compatible Slack objects at Build() time.
Composition objects
NewPlainText, NewMarkdown, and NewOption create the small values shared by blocks and elements.
Elements
Interactive controls include NewButton, NewCheckboxes, NewStaticSelect, and NewDatePicker.
Blocks
Every block uses the same New<Kind>Block naming pattern. Start with NewSectionBlock, NewActionsBlock, or NewHeaderBlock, then explore cards, carousels, containers, tables, charts, plans, task cards, rich text, and every other shared block capability.
Payloads and views
NewMessage, NewWebhookMessage, and NewMessageResponse build messages. NewModal and NewHomeTab build Slack views.
Higher-level components
NewPaginator renders one page plus navigation controls. NewAccordion expands collapsible sections directly inside Blocks(...).
Validation and JSON
ValidationError exposes stable error categories and field paths. Object is the JSON-compatible wire type returned by every completed builder.
The Java artifact uses immutable values built with concrete, fluent builders. Every completed block implements the official Slack Java SDK's LayoutBlock interface, so no adapter or conversion layer is required.
Composition objects
PlainText, MarkdownText, and Option create the small values shared by blocks and elements.
Elements
Interactive controls include ButtonElement, CheckboxesElement, StaticSelectElement, and DatePickerElement.
Blocks
Every block is named <Kind>Block and starts with a static builder() method. Begin with SectionBlock, ActionsBlock, or HeaderBlock, then explore cards, carousels, containers, tables, charts, plans, task cards, rich text, and the rest of the shared Block Kit surface.
Payloads and views
MessagePayload, WebhookMessage, and MessageResponse build complete JSON payloads. ModalView and HomeTabView build Slack view payloads.
Higher-level components
Paginator renders one page with previous and next controls. Accordion expands concrete, Slack-native collapsible containers.
Validation and JSON
ValidationException exposes stable categories and field paths. SlackObject is the immutable JSON-compatible contract returned by every completed builder.
The .NET package uses immutable values constructed with named arguments. Each constructor validates its arguments against Slack's documented rules, and every value writes compact Slack JSON, so no adapter or conversion layer sits between slackblocks and your HTTP client or Slack library.
Composition objects
PlainText, MarkdownText, and Option create the small values shared by blocks and elements. A string converts to the text object a field expects, so most code passes strings directly.
Elements
Interactive controls include ButtonElement, CheckboxesElement, StaticSelectElement, and DatePickerElement.
Blocks
Every block is named <Kind>Block and implements IBlock. Begin with SectionBlock, ActionsBlock, or HeaderBlock, then explore cards, carousels, containers, tables, charts, plans, task cards, rich text, and the rest of the shared Block Kit surface.
Payloads and views
MessagePayload, WebhookMessage, and MessageResponse build complete JSON payloads. ModalView and HomeTabView build Slack view payloads.
Higher-level components
Paginator renders one page with previous and next controls. Accordion combines Slack-native collapsible containers created by AccordionSection.
Validation and JSON
ValidationException exposes stable categories and field paths. SlackObject is the immutable base of every value, with ToJson() for compact JSON and ToJsonNode() for a mutable copy.
Ruby offers immutable keyword-constructed values for every shared block, element, composition object, payload, and view.
Composition objects
PlainText, MarkdownText, and Option are small values used by elements and blocks.
Elements and blocks
ButtonElement and other elements fit inside blocks. Start with SectionBlock, ActionsBlock, or HeaderBlock.
Payloads and components
MessagePayload, ModalView, and HomeTabView compose blocks for Slack. Paginator and Accordion return arrays of ordinary blocks.
Validation and JSON
ValidationError exposes a category and field path. Every value has as_json for a detached Slack hash and to_json for encoded JSON.
Guides
- Installation
- Using Blocks
- Sending Messages
- Recipe Book — complete end-to-end recipes for common message patterns.
- Troubleshooting & FAQ
- Migrating from 1.x to 2.x — upgrade guide for
1.xusers. - Contributing — developing and contributing to
slackblocksitself.
- Installation
- Sending Messages
- Recipe Book — complete end-to-end recipes for common message patterns.
- Contributing — developing and contributing to
slackblocksitself.