Rich Text

The Rich Text API lets you build inline-formatted content (bold, italic, strikethrough, code, links, mentions, lists, quotes, code blocks) without writing markdown by hand.

Structure:

• A RichTextBlock wraps one or more containers.
• Containers group elements: RichTextSection, RichTextList, RichTextQuote, RichTextCodeBlock.
• Elements are the leaf primitives: RichText (styled text), RichTextLink, RichTextUser, RichTextChannel, RichTextEmoji, RichTextUserGroup.

See the Rich-formatted alert cookbook recipe for a complete example.

Slack reference: https://api.slack.com/reference/block-kit/blocks#rich_text

Rich Text elements can be used to enhance text-based messages with code, list, quotations and formatted text (including options not available in traditional markdown like strikethrough).

These formatting elements can only be used within a RichTextBlock.

See: https://api.slack.com/reference/block-kit/blocks#rich_text.

Rich Text Elements (Primitives)

Rich text elements are the primitive elements used to populate the rich text object "containers", which are then fed into the RichTextBlock.

RichText

The core unit of the rich text API. Allows for the formatting of text with visual styles like bolding, italics and strikethroughs. Combined with higher-level containers like RichTextSection, RichText can be used to create complicated and deeply nested rich text within Slack messages.

Parameters:

Name	Type	Description	Default
text	str	the text content to render.	required
bold	bool | None	whether to render the given text in bold font.	None
italic	bool | None	whether to render the given text in italics.	None
strike	bool | None	whether to render the given text with a "strikethrough".	None
code	bool | None	whether to render the given text as an inline code snippet (monospaced).	None

Source code in slackblocks/rich_text/elements.py

class RichText(RichTextElement):
    """
    The core unit of the rich text API. Allows for the formatting of text
        with visual styles like bolding, italics and strikethroughs.
        Combined with higher-level containers like `RichTextSection`,
        `RichText` can be used to create complicated and deeply nested
        rich text within Slack messages.

    Args:
        text: the text content to render.
        bold: whether to render the given text in bold font.
        italic: whether to render the given text in italics.
        strike: whether to render the given text with a "strikethrough".
        code: whether to render the given text as an inline code snippet
            (monospaced).
    """

    def __init__(
        self,
        text: str,
        bold: bool | None = None,
        italic: bool | None = None,
        strike: bool | None = None,
        code: bool | None = None,
    ) -> None:
        super().__init__(type_=RichTextElementType.TEXT)
        self.text = text
        self.bold = bold
        self.italic = italic
        self.strike = strike
        self.code = code

    def _resolve(self) -> dict[str, Any]:
        return omit_none(
            {
                **super()._resolve(),
                "text": self.text,
                "style": _style_dict(
                    bold=self.bold, italic=self.italic, strike=self.strike, code=self.code
                ),
            }
        )

RichTextChannel

Rich text rendering of a Slack channel (e.g. #general).

See: https://api.slack.com/reference/block-kit/blocks#channel-element-type

Parameters:

Name	Type	Description	Default
channel_id	str	the ID of the channel to render. You can get this from the channel settings or the URL (if using Slack in the browser).	required
bold	bool | None	whether to render the given channel in bold font.	None
italic	bool | None	whether to render the given channel in italics.	None
strike	bool | None	whether to render the given channel with a "strikethrough".	None
highlight	bool | None	whether to give the channel a distinct highlight when rendered.	None
client_highlight	bool | None	a Slack-internal rendering hint accompanying mention-style elements. Rarely needed by app developers; pass None (the default) unless you have a specific reason to set it.	None
unlink	bool | None	whether to remove the link to the channel from the channel when rendered.	None

Source code in slackblocks/rich_text/elements.py

class RichTextChannel(RichTextElement):
    """
    Rich text rendering of a Slack channel (e.g. #general).

    See: <https://api.slack.com/reference/block-kit/blocks#channel-element-type>

    Args:
        channel_id: the ID of the channel to render. You can get this from
            the channel settings or the URL (if using Slack in the browser).
        bold: whether to render the given channel in bold font.
        italic: whether to render the given channel in italics.
        strike: whether to render the given channel with a "strikethrough".
        highlight: whether to give the channel a distinct highlight when rendered.
        client_highlight: a Slack-internal rendering hint accompanying
            mention-style elements. Rarely needed by app developers; pass
            ``None`` (the default) unless you have a specific reason to set
            it.
        unlink: whether to remove the link to the channel from the channel when
            rendered.
    """

    def __init__(
        self,
        channel_id: str,
        bold: bool | None = None,
        italic: bool | None = None,
        strike: bool | None = None,
        highlight: bool | None = None,
        client_highlight: bool | None = None,
        unlink: bool | None = None,
    ) -> None:
        super().__init__(RichTextElementType.CHANNEL)
        self.channel_id = channel_id
        self.bold = bold
        self.italic = italic
        self.strike = strike
        self.highlight = highlight
        self.client_highlight = client_highlight
        self.unlink = unlink

    def _resolve(self) -> dict[str, Any]:
        return omit_none(
            {
                **super()._resolve(),
                "channel_id": self.channel_id,
                "style": _style_dict(
                    bold=self.bold,
                    italic=self.italic,
                    strike=self.strike,
                    highlight=self.highlight,
                    client_highlight=self.client_highlight,
                    unlink=self.unlink,
                ),
            }
        )

RichTextEmoji

A rich text element for displaying an emoji.

The emoji can either be one built in to Slack or a custom workspace emoji.

See: https://api.slack.com/reference/block-kit/blocks#emoji-element-type

Parameters:

Name	Type	Description	Default
name	str	the unique name of the emoji to represent e.g. "wave".	required

Throws

InvalidUsageError: if the emoji name provided is empty.

Source code in slackblocks/rich_text/elements.py

class RichTextEmoji(RichTextElement):
    """
    A rich text element for displaying an emoji.

    The emoji can either be one built in to Slack or a custom workspace emoji.

    See: <https://api.slack.com/reference/block-kit/blocks#emoji-element-type>

    Args:
        name: the unique name of the emoji to represent e.g. "wave".

    Throws:
        InvalidUsageError: if the emoji `name` provided is empty.
    """

    def __init__(self, name: str) -> None:
        super().__init__(RichTextElementType.EMOJI)
        self.name = validate_string(name, field_name="name", min_length=1)

    def _resolve(self) -> dict[str, Any]:
        return {**super()._resolve(), "name": self.name}

RichTextLink

A rich text primitive to display links in text.

See: https://api.slack.com/reference/block-kit/blocks#link-element-type

Parameters:

Name	Type	Description	Default
url	str	the url which the link will point to.	required
text	str | None	the text to render with the link. If not provided, the raw URL will be used.	None
unsafe	bool | None	whether the link is "safe".	None
bold	bool | None	whether to render the given text in bold font.	None
italic	bool | None	whether to render the given text in italics.	None
strike	bool | None	whether to render the given text with a "strikethrough".	None
code	bool | None	whether to render the given text as an inline code snippet (monospaced).	None

Source code in slackblocks/rich_text/elements.py

class RichTextLink(RichTextElement):
    """
    A rich text primitive to display links in text.

    See: <https://api.slack.com/reference/block-kit/blocks#link-element-type>

    Args:
        url: the url which the link will point to.
        text: the text to render with the link. If not provided, the raw URL
            will be used.
        unsafe: whether the link is "safe".
        bold: whether to render the given text in bold font.
        italic: whether to render the given text in italics.
        strike: whether to render the given text with a "strikethrough".
        code: whether to render the given text as an inline code snippet
            (monospaced).
    """

    def __init__(
        self,
        url: str,
        text: str | None = None,
        unsafe: bool | None = None,
        bold: bool | None = None,
        italic: bool | None = None,
        strike: bool | None = None,
        code: bool | None = None,
    ) -> None:
        super().__init__(type_=RichTextElementType.LINK)
        self.url = url
        self.text = text
        self.unsafe = unsafe
        self.bold = bold
        self.italic = italic
        self.strike = strike
        self.code = code

    def _resolve(self) -> dict[str, Any]:
        return omit_none(
            {
                **super()._resolve(),
                "url": self.url,
                "text": self.text,
                "unsafe": self.unsafe,
                "style": _style_dict(
                    bold=self.bold, italic=self.italic, strike=self.strike, code=self.code
                ),
            }
        )

RichTextUser

Rich text element for representing users in RichTextBlocks.

See: https://api.slack.com/reference/block-kit/blocks#user-element-type.

Parameters:

Name	Type	Description	Default
user_id	str	the Slack ID of the user in question, you can get these from users' profiles or Slack client requests.	required
bold	bool | None	whether to render the given user in bold font.	None
italic	bool | None	whether to render the given user in italics.	None
strike	bool | None	whether to render the given user with a "strikethrough".	None
highlight	bool | None	whether to give the user a distinct highlight when rendered.	None
client_highlight	bool | None	a Slack-internal rendering hint accompanying mention-style elements. Rarely needed by app developers; pass None (the default) unless you have a specific reason to set it.	None
unlink	bool | None	whether to remove the link to the user from the channel when rendered.	None

Source code in slackblocks/rich_text/elements.py

class RichTextUser(RichTextElement):
    """
    Rich text element for representing users in
        [`RichTextBlocks`](/slackblocks/latest/reference/blocks/#blocks.RichTextBlock).

    See: <https://api.slack.com/reference/block-kit/blocks#user-element-type>.

    Args:
        user_id: the Slack ID of the user in question, you can get these
            from users' profiles or Slack client requests.
        bold: whether to render the given user in bold font.
        italic: whether to render the given user in italics.
        strike: whether to render the given user with a "strikethrough".
        highlight: whether to give the user a distinct highlight when rendered.
        client_highlight: a Slack-internal rendering hint accompanying
            mention-style elements. Rarely needed by app developers; pass
            ``None`` (the default) unless you have a specific reason to set
            it.
        unlink: whether to remove the link to the user from the channel when
            rendered.
    """

    def __init__(
        self,
        user_id: str,
        bold: bool | None = None,
        italic: bool | None = None,
        strike: bool | None = None,
        highlight: bool | None = None,
        client_highlight: bool | None = None,
        unlink: bool | None = None,
    ) -> None:
        super().__init__(RichTextElementType.USER)
        self.user_id = user_id
        self.bold = bold
        self.italic = italic
        self.strike = strike
        self.highlight = highlight
        self.client_highlight = client_highlight
        self.unlink = unlink

    def _resolve(self) -> dict[str, Any]:
        return omit_none(
            {
                **super()._resolve(),
                "user_id": self.user_id,
                "style": _style_dict(
                    bold=self.bold,
                    italic=self.italic,
                    strike=self.strike,
                    highlight=self.highlight,
                    client_highlight=self.client_highlight,
                    unlink=self.unlink,
                ),
            }
        )

RichTextUserGroup

Rich text element for representing groups of users in RichTextBlocks`.

See: https://api.slack.com/reference/block-kit/blocks#user-element-type.

Parameters:

Name	Type	Description	Default
user_group_id	str	the Slack ID of the user group being represented.	required
bold	bool | None	whether to render the given user in bold font.	None
italic	bool | None	whether to render the given user in italics.	None
strike	bool | None	whether to render the given user with a "strikethrough".	None
highlight	bool | None	whether to give the user a distinct highlight when rendered.	None
client_highlight	bool | None	a Slack-internal rendering hint accompanying mention-style elements. Rarely needed by app developers; pass None (the default) unless you have a specific reason to set it.	None
unlink	bool | None	whether to remove the link to the user from the channel when rendered.	None

Source code in slackblocks/rich_text/elements.py

class RichTextUserGroup(RichTextElement):
    """
    Rich text element for representing groups of users in
        [`RichTextBlocks`](/slackblocks/latest/reference/blocks/#blocks.RichTextBlock)`.

    See: <https://api.slack.com/reference/block-kit/blocks#user-element-type>.

    Args:
        user_group_id: the Slack ID of the user group being represented.
        bold: whether to render the given user in bold font.
        italic: whether to render the given user in italics.
        strike: whether to render the given user with a "strikethrough".
        highlight: whether to give the user a distinct highlight when rendered.
        client_highlight: a Slack-internal rendering hint accompanying
            mention-style elements. Rarely needed by app developers; pass
            ``None`` (the default) unless you have a specific reason to set
            it.
        unlink: whether to remove the link to the user from the channel when
            rendered.
    """

    def __init__(
        self,
        user_group_id: str,
        bold: bool | None = None,
        italic: bool | None = None,
        strike: bool | None = None,
        highlight: bool | None = None,
        client_highlight: bool | None = None,
        unlink: bool | None = None,
    ) -> None:
        super().__init__(RichTextElementType.USER_GROUP)
        self.user_group_id = user_group_id
        self.bold = bold
        self.italic = italic
        self.strike = strike
        self.highlight = highlight
        self.client_highlight = client_highlight
        self.unlink = unlink

    def _resolve(self) -> dict[str, Any]:
        return omit_none(
            {
                **super()._resolve(),
                "usergroup_id": self.user_group_id,
                "style": _style_dict(
                    bold=self.bold,
                    italic=self.italic,
                    strike=self.strike,
                    highlight=self.highlight,
                    client_highlight=self.client_highlight,
                    unlink=self.unlink,
                ),
            }
        )

_style_dict

_style_dict(**flags)

Build a rich text "style" sub-object from named boolean flags.

Any flag that is explicitly None is dropped. If every flag is dropped (i.e. nothing was set), returns None so the caller can decide whether to emit the style key at all.

Source code in slackblocks/rich_text/elements.py

def _style_dict(**flags: bool | None) -> dict[str, bool] | None:
    """Build a rich text "style" sub-object from named boolean flags.

    Any flag that is explicitly ``None`` is dropped. If every flag is dropped
    (i.e. nothing was set), returns ``None`` so the caller can decide whether
    to emit the ``style`` key at all.
    """
    style = omit_none(flags)
    return style if style else None

Rich Text Objects (Containers)

Rich text objects are containers for rich text elements.

These objects form the contents of the RichTextBlock.

ListType

An Enum that lists the available types of rich text lists.

• ListType.BULLET: an unorderd (bulleted) list.
• ListType.ORDERED: an ordered (numbered) list.

Source code in slackblocks/rich_text/objects.py

class ListType(Enum):
    """
    An `Enum` that lists the available types of rich text lists.

    - `ListType.BULLET`: an unorderd (bulleted) list.
    - `ListType.ORDERED`: an ordered (numbered) list.
    """

    BULLET = "bullet"
    ORDERED = "ordered"

    @classmethod
    def all(cls) -> list[str]:
        return [list_type.value for list_type in ListType]

RichTextCodeBlock

A rich text element for representing blocks of code in RichTextBlocks.

This is roughly equivalent to the triple-backtick code syntax in markdown.

See: https://api.slack.com/reference/block-kit/blocks#rich_text_preformatted.

Parameters:

Name	Type	Description	Default
elements	RichTextElement | list[RichTextElement]	one or more rich text primitive objexts (e.g. RichText).	required
border	int | None	the thickness (in pixels) of the border around the code block.	None

Throws

InvalidUsageError: if any of the items in elements aren't valid rich text elements.

Source code in slackblocks/rich_text/objects.py

class RichTextCodeBlock(RichTextObject):
    """
    A rich text element for representing blocks of code in
        [`RichTextBlocks`](/slackblocks/latest/reference/blocks/#blocks.RichTextBlock).

    This is roughly equivalent to the triple-backtick ```code``` syntax in markdown.

    See: <https://api.slack.com/reference/block-kit/blocks#rich_text_preformatted>.

    Args:
        elements: one or more rich text primitive objexts
            (e.g. [`RichText`](/slackblocks/latest/reference/rich_text/#rich_text.RichText)).
        border: the thickness (in pixels) of the border around the code block.

    Throws:
        InvalidUsageError: if any of the items in `elements` aren't valid rich
            text elements.
    """

    def __init__(
        self,
        elements: RichTextElement | list[RichTextElement],
        border: int | None = None,
    ) -> None:
        super().__init__(type_=RichTextObjectType.PREFORMATTED)
        self.elements = coerce_to_list(
            elements,
            (
                RichText,
                RichTextChannel,
                RichTextEmoji,
                RichTextLink,
                RichTextUser,
                RichTextUserGroup,
            ),
        )
        self.border = border

    def _resolve(self) -> dict[str, Any]:
        return resolve(
            {
                **super()._resolve(),
                "elements": [element for element in self.elements if element is not None]
                if self.elements is not None
                else None,
                "border": self.border,
            }
        )

RichTextList

Renders to a HTML list containing rich text elements.

See: https://api.slack.com/reference/block-kit/blocks#rich_text_list.

Parameters:

Name	Type	Description	Default
style	str | ListType	one of ListType.BULLET or ListType.ORDERED.	required
elements	RichTextSection | list[RichTextSection]	a list of (possibly nested) RichTextSection elements. Each object in this list will be rendered as a list item.	required
indent	int | None	indent (in pixels) of each list item.	None
offset	int | None	offset (in pixels) of each list item.	0
border	int | None	thickness (in pixels) of the (optional) border around the list.	0

Throws

InvalidUsageError: if style is not a valid ListType or any of the items in elements isn't a valid RichTextSection.

Source code in slackblocks/rich_text/objects.py

class RichTextList(RichTextObject):
    """
    Renders to a HTML list containing rich text elements.

    See: <https://api.slack.com/reference/block-kit/blocks#rich_text_list>.

    Args:
        style: one of `ListType.BULLET` or `ListType.ORDERED`.
        elements: a list of (possibly nested) `RichTextSection` elements.
            Each object in this list will be rendered as a list item.
        indent: indent (in pixels) of each list item.
        offset: offset (in pixels) of each list item.
        border: thickness (in pixels) of the (optional) border around the list.

    Throws:
        InvalidUsageError: if style is not a valid `ListType` or any of the
            items in `elements` isn't a valid `RichTextSection`.
    """

    def __init__(
        self,
        style: str | ListType,
        elements: RichTextSection | list[RichTextSection],
        indent: int | None = None,
        offset: int | None = 0,
        border: int | None = 0,
    ) -> None:
        super().__init__(type_=RichTextObjectType.LIST)
        if isinstance(style, str):
            if style in ListType.all():
                self.style = style
            else:
                raise TypeMismatchError(f"`style` must be one of [{ListType.all()}]")
        elif isinstance(style, ListType):
            self.style = style.value
        self.elements = coerce_to_list(elements, RichTextSection, min_size=1)
        self.indent = validate_int(indent, allow_none=True)
        self.offset = validate_int(offset, allow_none=True)
        self.border = validate_int(border, allow_none=True)

    def _resolve(self) -> dict[str, Any]:
        return resolve(
            {
                **super()._resolve(),
                "elements": [element for element in self.elements if element is not None]
                if self.elements is not None
                else None,
                "style": self.style,
                "indent": self.indent,
                "offset": self.offset,
                "border": self.border,
            }
        )

RichTextQuote

A rich text object for representing a block quote.

Block quotes are presented with a vertical bar to the left hand side of the text.

See: https://api.slack.com/reference/block-kit/blocks#rich_text_quote

Parameters:

Name	Type	Description	Default
elements	RichTextElement | list[RichTextElement]	one or more rich text primitive objexts (e.g. RichText).	required
border	int | None	the thickness (in pixels) of the border around the code block.	None

Source code in slackblocks/rich_text/objects.py

class RichTextQuote(RichTextObject):
    """
    A rich text object for representing a block quote.

    Block quotes are presented with a vertical bar to the left hand side of
        the text.

    See: <https://api.slack.com/reference/block-kit/blocks#rich_text_quote>

    Args:
        elements: one or more rich text primitive objexts
            (e.g. [`RichText`](/slackblocks/latest/reference/rich_text/#rich_text.RichText)).
        border: the thickness (in pixels) of the border around the code block.
    """

    def __init__(
        self,
        elements: RichTextElement | list[RichTextElement],
        border: int | None = None,
    ) -> None:
        super().__init__(RichTextObjectType.QUOTE)
        self.elements = coerce_to_list(
            elements,
            (
                RichText,
                RichTextChannel,
                RichTextEmoji,
                RichTextLink,
                RichTextUser,
                RichTextUserGroup,
            ),
        )
        self.border = border

    def _resolve(self) -> dict[str, Any]:
        return resolve(
            {
                **super()._resolve(),
                "elements": [element for element in self.elements if element is not None]
                if self.elements is not None
                else None,
                "border": self.border,
            }
        )

RichTextSection

The most basic rich text container object, which takes rich text elements and renders them when RichTextSection is passed to a RichTextBlock.

See: https://api.slack.com/reference/block-kit/blocks#rich_text_section.

Parameters:

Name	Type	Description	Default
elements	RichTextElement | list[RichTextElement]	one or more rich text elements that will form the content of the section. e.g. RichText, RichTextLink.	required

Throws

InvalidUsageError: if any of the items passed to elements isn't a valid RichTextObject.

Source code in slackblocks/rich_text/objects.py

class RichTextSection(RichTextObject):
    """
    The most basic rich text container object, which takes rich text elements
        and renders them when `RichTextSection` is passed to a
        [`RichTextBlock`](/slackblocks/latest/reference/blocks/#blocks.RichTextBlock).

    See: <https://api.slack.com/reference/block-kit/blocks#rich_text_section>.

    Args:
        elements: one or more rich text elements that will form the content of the section.
            e.g. `RichText`, `RichTextLink`.

    Throws:
        InvalidUsageError: if any of the items passed to `elements` isn't a valid
            `RichTextObject`.
    """

    def __init__(self, elements: RichTextElement | list[RichTextElement]) -> None:
        super().__init__(type_=RichTextObjectType.SECTION)
        self.elements = coerce_to_list(
            elements,
            class_=(
                RichTextChannel,
                RichTextEmoji,
                RichTextLink,
                RichText,
                RichTextUser,
                RichTextUserGroup,
            ),
            min_size=1,
        )

    def _resolve(self) -> dict[str, Any]:
        return resolve({**super()._resolve(), "elements": self.elements})