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​

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​

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​

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​

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​

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​

from slackblocks import DividerBlock

DividerBlock(block_id="fake_block_id")

File Block​

from slackblocks import FileBlock

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

Context Block​

from slackblocks import ContextBlock, Text

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

Actions Block​

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​

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="How to use slackblocks",
    block_id="fake_block_id",
    thumbnail_url="https://example.com/thumb.png",
    title="Getting Started",
    video_url="https://example.com/video.mp4",
    author_name="The slackblocks docs",
    description="A short walkthrough.",
    provider_name="example.com",
    title_url="https://example.com",
)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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",
)