Skip to main content

Using Blocks

Blocks are the fundamental visual units of a Slack message. Each block type renders as a different UI component (a section of text, a header, a divider, an image, a row of buttons, and so on). A Message is composed of one or more blocks, rendered top-to-bottom.

This page walks through every block type supported by slackblocks, with:

  • A short description of what the block is for.
  • The slackblocks code to construct it in your selected language.
  • The JSON payload that's produced.
  • A screenshot of how it looks in Slack.

For the reverse mapping — looking up a class by name — see the Blocks reference. For interactive UI bits (buttons, menus, date pickers) that go inside blocks, see Elements.

Section Block​

A section is the most versatile block. It shows text, a two-column grid of fields, or both, and can carry one interactive accessory such as a button, menu, or image.

Provide text, fields, or both. text allows up to 3,000 characters, and fields allows up to 10 items of up to 2,000 characters each.

from slackblocks import CheckboxGroup, Option, SectionBlock

SectionBlock(
    text="This is a section block with a checkbox accessory.",
    block_id="fake_block_id",
    accessory=CheckboxGroup(
        action_id="checkboxes-action",
        options=[
            Option(
                text="*Your Only Option*",
                value="option_one"
            )
        ]
    )
)

Rich Text Block​

Rich text carries formatted content built from sections, lists, preformatted code, and quotes. Inline elements add bold, italic, strikethrough, and code styling, along with links, emoji, and user, channel, or user group mentions.

Required: elements.

from slackblocks import RichTextBlock, RichTextSection, RichText

RichTextBlock(
    RichTextSection(
        [
            RichText(
                "You 'bout to witness hip-hop in its most purest\n",
                bold=True,
            ),
            RichText(
                "Most rawest form, flow almost flawless\n",
                strike=True,
            ),
            RichText(
                "Most hardest, most honest known artist\n",
                italic=True,
            ),
        ]
    ),
    block_id="fake_block_id",
)

Header Block​

A header shows large, bold plain text that introduces a group of blocks. Plain strings are converted to Slack plain_text objects automatically.

Required: text (up to 150 characters).

from slackblocks import HeaderBlock

HeaderBlock(
    "This is a header block",
    block_id="fake_block_id",
)

Markdown Block​

Slack added the markdown block type in 2024, primarily for AI / agentic apps. Unlike the mrkdwn text inside a Section Block, MarkdownBlock renders GitHub-flavored Markdown, supporting tables, code blocks, and richer list semantics.

text is required (1 - 12,000 characters).

from slackblocks import MarkdownBlock

MarkdownBlock(
    text="**Hello!** Markdown blocks support _GitHub-flavored_ syntax.",
    block_id="fake_block_id",
)

See the Slack reference for the supported Markdown features.

Image Block​

An image block displays a standalone image from a URL, with alternative text for screen readers and an optional plain-text title.

Required: image_url (up to 3,000 characters) and alt_text (up to 2,000 characters).

from slackblocks import ImageBlock

ImageBlock(
    image_url="https://api.slack.com/img/blocks/bkb_template_images/beagle.png",
    alt_text="a beagle",
    title="dog",
    block_id="fake_block_id",
)

Input Block​

An input block pairs a label with one input element, such as a text input, select menu, or date picker, to collect a value from the user. Input blocks are most common in modals, and can also appear in messages and App Home.

Required: label (up to 2,000 characters) and element. Set optional to allow submission without a value, and dispatch_action to receive an interaction payload as the value changes.

from slackblocks import InputBlock, Text, TextType, PlainTextInput

InputBlock(
    label=Text("Label", type_=TextType.PLAINTEXT, emoji=True),
    hint=Text("Hint", type_=TextType.PLAINTEXT, emoji=True),
    element=PlainTextInput(action_id="action"),
    block_id="fake_block_id",
    optional=True,
)

Divider Block​

A divider draws a horizontal rule between blocks, much like an HTML <hr> element.

No fields are required.

from slackblocks import DividerBlock

DividerBlock(block_id="fake_block_id")

File Block​

A file block displays a remote file that was previously added to Slack with the files.remote.add API. It references the existing file by ID and does not upload anything itself.

Required: external_id. source defaults to remote, the only value Slack currently accepts.

from slackblocks import FileBlock

FileBlock(
    external_id="external_id",
    block_id="fake_block_id",
)

Context Block​

A context block shows small, secondary images and text, such as an author, a timestamp, or a status line beneath other content.

Required: elements (up to 10 images or text objects).

from slackblocks import ContextBlock, Text

ContextBlock(
    elements=[
        Text("Hello, world!"),
    ],
    block_id="fake_block_id"
)

Actions Block​

An actions block holds a row of interactive elements, such as buttons, select menus, overflow menus, checkboxes, and date pickers.

Required: elements (up to 25 elements).

from slackblocks import ActionsBlock, CheckboxGroup, Option

ActionsBlock(
    block_id="fake_block_id",
    elements=CheckboxGroup(
        action_id="actionId-0",
        options=[
            Option(text="*a*", value="a", description="*a*"),
            Option(text="*b*", value="b", description="*b*"),
            Option(text="*c*", value="c", description="*c*"),
        ],
    ),
)

Table Block​

A table block lays out raw text and rich text cells in rows and columns. Optional column_settings control each column's alignment and whether its text wraps.

Required: rows. Every row must have the same number of cells, and column_settings needs one entry for every column.

from slackblocks import (
    ColumnSettings,
    RawText,
    RichText,
    RichTextLink,
    RichTextSection,
    TableBlock,
)

TableBlock(
    block_id="fake_block_id",
    column_settings=[
        ColumnSettings(align="right", is_wrapped=True),
        ColumnSettings(align="left"),
    ],
    rows=[
        [
            RichTextSection(
                elements=[RichText(text="Header 1", bold=True)],
            ),
            RichTextSection(
                elements=[RichText(text="Header 2", bold=True)],
            ),
        ],
        [
            RawText(text="Datum 1"),
            RichTextSection(
                elements=[
                    RichTextLink(
                        url="https://slack.com",
                        text="Datum 2",
                    )
                ],
            ),
        ],
    ],
)

Video Block​

Embeds a video from a Slack-supported provider such as YouTube or Vimeo. Plain strings supplied for title and description are converted to Slack plain_text objects automatically.

Required: alt_text, thumbnail_url, title, video_url. Slack restricts which domains may be embedded — supplying an unsupported URL will produce a Slack API error rather than an InvalidUsageError at construction.

from slackblocks import VideoBlock

VideoBlock(
    alt_text="Use the Events API to create a dynamic App Home",
    block_id="fake_block_id",
    thumbnail_url="https://i.ytimg.com/vi/8876OZV_Yy0/hqdefault.jpg",
    title="Use the Events API to create a dynamic App Home",
    video_url="https://www.youtube.com/embed/8876OZV_Yy0?feature=oembed&autoplay=1",
    description="Slack sure is nifty!",
    title_url="https://www.youtube.com/watch?v=8876OZV_Yy0",
)

See the Slack reference for the full list of optional fields and provider requirements.

Alert Block​

Alerts add a severity-labelled notice to a modal.

Required: text (up to 200 characters). level sets the severity: default, info, warning, error, or success.

from slackblocks import AlertBlock

AlertBlock(
    "The deployment needs attention.",
    level="warning",
    block_id="fake_block_id",
)

Card Block​

Cards combine text, images, Slack-provided icons, and up to three buttons in a compact panel.

Provide at least one of hero_image, title, actions, or body. An image icon and a slack_icon cannot be combined.

from slackblocks import Button, CardBlock, SlackIcon

CardBlock(
    title="Build complete",
    body="Version 2.1.0 is ready to deploy.",
    slack_icon=SlackIcon("rocket"),
    actions=Button("Open build", "open_build"),
    block_id="fake_block_id",
)

A carousel presents between one and ten cards in a horizontally scrolling collection.

Required: elements.

from slackblocks import CardBlock, CarouselBlock

CarouselBlock([
    CardBlock(title="First result", block_id="card_1"),
    CardBlock(title="Second result", block_id="card_2"),
], block_id="fake_block_id")

Container Block​

Containers group up to ten related child blocks under a plain-text or rich-text title.

Required: child_blocks, plus either title or rich_text_title.

from slackblocks import ContainerBlock, SectionBlock

ContainerBlock(
    title="Deployment summary",
    child_blocks=[
        SectionBlock("All systems operational.", block_id="child_1"),
    ],
    has_header_divider=True,
    block_id="fake_block_id",
)

Context Actions Block​

Context actions hold feedback controls or compact icon buttons. Slack currently offers the trash icon for icon buttons.

Required: elements (up to 5).

from slackblocks import ContextActionsBlock, FeedbackButton, FeedbackButtons

ContextActionsBlock([
    FeedbackButtons(
        positive_button=FeedbackButton("Good", "positive"),
        negative_button=FeedbackButton("Bad", "negative"),
        action_id="response_feedback",
    )
], block_id="fake_block_id")

Data Table Block​

Data tables support raw text, sortable raw numbers, and rich-text body cells. They require a header plus at least one data row.

Required: rows and caption. Tables hold up to 200 data rows, every row must have the same number of cells, and all cell text together is limited to 20,000 characters.

from slackblocks import DataTableBlock, RawNumber, RawText

DataTableBlock(
    caption="Team scores",
    rows=[
        [RawText("Name"), RawText("Score")],
        [RawText("Alice"), RawNumber(42, "42")],
    ],
    block_id="fake_block_id",
)

Data Visualization Block​

Slack can render pie charts or axis-based bar, area, and line charts directly from Block Kit data.

Required: title (up to 50 characters) and chart.

from slackblocks import ChartSegment, DataVisualizationBlock, PieChart

DataVisualizationBlock(
    title="Incidents by severity",
    chart=PieChart([
        ChartSegment("High", 3),
        ChartSegment("Low", 12),
    ]),
    block_id="fake_block_id",
)

Task Card Block​

Task cards show a task's state, optional rich-text details or output, and the URL sources used to produce it.

Required: task_id and title.

from slackblocks import TaskCardBlock, URLSource

TaskCardBlock(
    task_id="weather_1",
    title="Fetch weather data",
    status="complete",
    sources=[URLSource("https://weather.com/", "weather.com")],
    block_id="fake_block_id",
)

Plan Block​

A plan groups task cards. slackblocks automatically renders nested tasks in Slack's plan-specific wire format.

Required: title.

from slackblocks import PlanBlock, TaskCardBlock

PlanBlock(
    title="Release plan",
    tasks=[
        TaskCardBlock("test", "Run the test suite", status="complete"),
        TaskCardBlock("deploy", "Deploy the release", status="pending"),
    ],
    block_id="fake_block_id",
)
Last updated on