Using Blocks

Section Block

A section is one of the most flexible blocks available - it can be used as a simple text block, or with any of the available block elements.

Section blocks can also optionally be given an "accessory," which is typically one of the interactive Elements.

Parameters:

Name	Type	Description	Default
`text`	`Optional[TextLike]`	text to include in the block. Can be a string or `Text` object (of either `mrkdwn` or `plaintext` variety). Defaults to markdown if unspecified. One of either `text` or `fields` must be provided.	`None`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`
`fields`	`Optional[Union[TextLike, List[TextLike]]]`	a list of text objects. One of either `text` or `fields` must be provided.	`None`
`accessory`	`Optional[Element]`	an optional Element object that will take a secondary place in the block (after or to the side of `text` or `fields`).	`None`

Throws

InvalidUsageError: if any of the provided arguments fail validation checks.

slackblocksJSONSlack UI

from slackblocks import Checkboxes, 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"
            )
        ]
    )
)

{
    "type": "section",
    "block_id": "fake_block_id",
    "text": {
        "type": "mrkdwn",
        "text": "This is a section block with a checkbox accessory."
    },
    "accessory": {
        "type": "checkboxes",
        "options": [
            {
                "text": {
                    "type": "mrkdwn",
                    "text": "*Your Only Option*"
                },
                "value": "option_one"
            }
        ],
        "action_id": "checkboxes-action"
    }
}

An example of the UI output of a Section Block

Rich Text Block

A RichTextBlock is used to provide easier rich text formatting than standard markdown text (e.g. in a SectionBlock) and access to text formatting features not available in traditional markdown (e.g. strikethrough). See the various rich text elements you can include here.

Parameters:

Name	Type	Description	Default
`elements`	`Union[RichTextObject, List[RichTextObject]]`	a single rich text element or a list of those elements.	required
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

Throws

InvalidUsageError: if the elements in elements are not valid rich text elements.

slackblocksJSONSlack UI

from slackblock import RichTextBlock, RichTextSection, RichText

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

{
    "type": "rich_text",
    "block_id": "fake_block_id",
    "elements": [
        {
            "type": "rich_text_section",
            "elements": [
                {
                    "type": "text",
                    "text": "You 'bout to witness hip-hop in its most purest\n",
                    "style": {
                        "bold": true
                    }
                },
                {
                    "type": "text",
                    "text": "Most rawest form, flow almost flawless\n",
                    "style": {
                        "strike": true
                    }
                },
                {
                    "type": "text",
                    "text": "Most hardest, most honest known artist\n",
                    "style": {
                        "italic": true
                    }
                }
            ]
        }
    ]
}

An example of the UI output of a Rich Text Block

Header Block

A Header Block is a plain-text block that displays in a larger, bold font.

Parameters:

Name	Type	Description	Default
`text`	`Union[str, Text]`	the text that will be rendered as a heading.	required
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

slackblocksJSONSlack UI

from slackblocks import HeaderBlock

HeaderBlock(
    "This is a header block",
)

{
    "type": "header",
    "text": {
        "type": "plain_text",
        "text": "This is a header block",
        "emoji": true
    }
}

An example of the UI output of a Header Block

Image Block

An Image Block contains a single graphic, accessed by URL.

Parameters:

Name	Type	Description	Default
`image_url`	`str`	the URL pointing to the image file you want to display.	required
`alt_text`	`Optional[str]`	alternative text for accessibility purposes and when the image fails to load.	`' '`
`title`	`Optional[Union[Text, str]]`	an optional text title to be presented with the image.	`None`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

Throws

InvalidUsageError: when one or more of the provided args fails validation.

slackblocksJSONSlack UI

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

{
    "type": "image",
    "block_id": "fake_block_id",
    "image_url": "https://api.slack.com/img/blocks/bkb_template_images/beagle.png",
    "alt_text": "a beagle",
    "title": {
        "type": "plain_text",
        "text": "dog"
    }
}

An example of the UI output of an Image Block

Input Block

A block that collects information from users - it can hold a plain-text input element, a checkbox element, a radio button element, a select menu element, a multi-select menu element, or a datepicker.

Parameters:

Name	Type	Description	Default
`label`	`TextLike`	the name which identifies the input field.	required
`element`	`Element`	an interactive Element (e.g. a text field).	required
`dispatch_action`	`bool`	whether the Element should trigger the sending of a `block_actions` payload.	`False`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`
`hint`	`Optional[TextLike]`	an optional additional guide on what input the user should prodive.	`None`
`optional`	`bool`	whether this input field may be empty when the user submits e.g. the modal.	`False`

Throws

InvalidUsageError: when any of the provided arguments fail validation.

slackblocksJSONSlack UI

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

{
    "type": "input",
    "block_id": "fake_block_id",
    "label": {
        "type": "plain_text",
        "text": "Label",
        "emoji": true
    },
    "element": {
        "type": "plain_text_input",
        "action_id": "action"
    },
    "hint": {
        "type": "plain_text",
        "text": "Hint",
        "emoji": true
    },
    "optional": true
}

An example of the UI output of an Input Block

Divider Block

A content divider, like an <hr> in HTML, to split up different blocks inside of a message.

Parameters:

Name	Type	Description	Default
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

slackblocksJSONSlack UI

from slackblocks import DividerBlock

DividerBlock()

{
    "type": "divider"
}

An example of the UI output of an Divider Block

File Block

Displays a remote file (e.g. a PDF).

For details on how remote files are exposed to Slack, see https://api.slack.com/messaging/files#adding.

Parameters:

Name	Type	Description	Default
`external_id`	`str`	the ID assigned to the remote file when it was added to Slack.	required
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	required
`source`	`str`	always "remote" as per the Slack API (may change in the future).	`'remote'`

slackblocksJSONSlack UI

from slackblocks import FileBlock

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

{
    "type": "file",
    "external_id": "external_id",
    "source": "remote",
    "block_id": "fake_block_id"
}

An example of the UI output of an File Block * Note that this example comes from the Slack Web API docs.

Context Block

A ContextBlock displays contextul message info, including both images and text.

Parameters:

Name	Type	Description	Default
`elements`	`Optional[List[Union[Element, CompositionObject]]]`	a list of `Text` objects and `Image` elements.	`None`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

Throws

InvalidUsageError: when items in elements are not Text or Image or exceed 10 items.

slackblocksJSONSlack UI

from slackblocks import ContextBlock, Text

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

{
    "type": "context",
    "block_id": "fake_block_id",
    "elements": [
        {
            "type": "mrkdwn",
            "text": "Hello, world!"
        }
    ]
}

An example of the UI output of an Context Block

Actions Block

A Block that is used to hold interactive elements (normally for users to interface with).

Parameters:

Name	Type	Description	Default
`elements`	`Optional[List[Element]]`	a list of Elements (up to a maximum of 25).	`None`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

Throws

InvalidUsageError: if any of the items in elements are invalid.

slackblocksJSONSlack UI

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

{
    "type": "actions",
    "block_id": "fake_block_id",
    "elements": [
        {
            "type": "checkboxes",
            "action_id": "actionId-0",
            "options": [
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*a*"
                    },
                    "value": "a",
                    "description": {
                        "type": "plain_text",
                        "text": "*a*"
                    }
                },
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*b*"
                    },
                    "value": "b",
                    "description": {
                        "type": "plain_text",
                        "text": "*b*"
                    }
                },
                {
                    "text": {
                        "type": "mrkdwn",
                        "text": "*c*"
                    },
                    "value": "c",
                    "description": {
                        "type": "plain_text",
                        "text": "*c*"
                    }
                }
            ]
        }
    ]
}

An example of the UI output of an Actions Block

Table Block

A TableBlock displays data in a table format.

Parameters:

Name	Type	Description	Default
`rows`	`List[List[Union[RawText, RichTextObject]]]`	a list of lists of `RawText` or `RichTextObject` objects.	required
`column_settings`	`Optional[List[ColumnSettings]]`	a list of `ColumnSettings` objects.	`None`
`block_id`	`Optional[str]`	you can use this field to provide a deterministic identifier for the block.	`None`

Throws

InvalidUsageError: when items in rows are not RawText or RichTextObject objects. InvalidUsageError: when the number of column_settings does not match the number of columns in each row. InvalidUsageError: when the number of rows is greater than 100. InvalidUsageError: when the number of columns in a row is greater than 20. InvalidUsageError: when the number of column_settings is greater than 20.

slackblocksJSONSlack UI

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

{
    "blocks": [
        {
            "type": "table",
            "rows": [
                [
                    {
                        "type": "rich_text",
                        "elements": [
                            {
                                "type": "rich_text_section",
                                "elements": [
                                    {
                                        "type": "text",
                                        "text": "Header 1",
                                        "style": {
                                            "bold": true
                                        }
                                    }
                                ]
                            }
                        ]
                    },
                    {
                        "type": "rich_text",
                        "elements": [
                            {
                                "type": "rich_text_section",
                                "elements": [
                                    {
                                        "type": "text",
                                        "text": "Header 2",
                                        "style": {
                                            "bold": true
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                ],
                [
                    {
                        "type": "rich_text",
                        "elements": [
                            {
                                "type": "rich_text_section",
                                "elements": [
                                    {
                                        "type": "text",
                                        "text": "Datum 1"
                                    }
                                ]
                            }
                        ]
                    },
                    {
                        "type": "rich_text",
                        "elements": [
                            {
                                "type": "rich_text_section",
                                "elements": [
                                    {
                                        "type": "text",
                                        "text": "Datum 2"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            ]
        }
    ]
}

An example of the UI output of a Table Block