Welcome to slackblocks!
slackblocks builds Slack messages with the Block Kit API in Python, TypeScript, and Go — 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, and Go.
- 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, and Go integrates with
slack-go/slackfor delivery.
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.
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.