Elements and Composites

Purpose and Scope

This document details Block Kit elements and composite objects, which are the foundational building blocks used within Slack Block Kit blocks. Elements are interactive components (buttons, images) and text display objects, while composites are complex objects that combine multiple elements to provide advanced functionality like confirmation dialogs.

For information about block-level components (ActionsBlock, SectionBlock, etc.) that contain these elements, see Block Types. For the contract interfaces that govern these components, see Block Kit Contracts.

---

Overview

Block Kit elements and composites serve different roles in the Slack message composition hierarchy:

Elements are primitive components that render content or provide interactivity. These include text objects (for displaying formatted text), buttons, images, and other UI controls.

Composites are sophisticated objects that bundle multiple elements together to provide complex functionality. The primary composite in the system is ConfirmObject, which creates confirmation dialogs for user actions.

Diagram: Block Kit Component Hierarchy

Sources: All files in src/Slack/BlockKit/Composites/

---

Text Objects

Text objects are the most fundamental elements in Block Kit, used to display text content throughout blocks. The system provides two text object implementations with different capabilities.

Class Hierarchy

Diagram: Text Object Class Hierarchy

Sources: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php1-63 src/Slack/BlockKit/Composites/TextObject.php1-67

---

PlainTextOnlyTextObject

The PlainTextOnlyTextObject class represents text that renders as plain, unformatted content in Slack. It implements the ObjectContract interface and provides basic text display functionality with automatic length validation and truncation.

Properties and Construction

Property	Type	Description
$text	string	The text content to display
$emoji	?bool	Whether to escape emojis into colon format

The constructor enforces text length constraints: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php25-36

Constructor signature: __construct(string $text, int $maxLength = 3000, int $minLength = 1)

If text exceeds $maxLength, it is automatically truncated with an ellipsis appended. If text is shorter than $minLength, an InvalidArgumentException is thrown.

Methods

emoji(): static src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php41-46

Configures the text object to escape emoji characters into colon notation (:emoji_name:).

toArray(): array src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php51-62

Serializes the object to the Slack API format:

Usage Context

PlainTextOnlyTextObject is used in contexts where Slack requires plain text without formatting, such as:

• Button labels in ButtonElement
• Titles in ConfirmObject src/Slack/BlockKit/Composites/ConfirmObject.php16
• Confirm/deny button labels in ConfirmObject src/Slack/BlockKit/Composites/ConfirmObject.php30-37

Sources: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php1-63

---

TextObject

The TextObject class extends PlainTextOnlyTextObject to add Markdown formatting support and additional configuration options. This is the primary text object used throughout Block Kit blocks.

Additional Properties

Property	Type	Description
$type	string	Text format: 'plain_text' or 'mrkdwn'
$verbatim	?bool	Disable auto-linking for markdown (mrkdwn only)

Methods

markdown(): static src/Slack/BlockKit/Composites/TextObject.php28-33

Switches the text object format to Markdown (mrkdwn), enabling Slack's markdown formatting syntax including bold, italic, lists, and links.

verbatim(): static src/Slack/BlockKit/Composites/TextObject.php40-45

When set, prevents automatic conversion of URLs to links, @-mentions to user references, and #-mentions to channel references. Only applicable when using markdown format.

toArray(): array src/Slack/BlockKit/Composites/TextObject.php50-66

Serializes the object with conditional field inclusion based on format type:

• When type is 'mrkdwn': excludes emoji field, includes verbatim if set
• When type is 'plain_text': excludes verbatim field, includes emoji if set

Diagram: TextObject Serialization Logic

Sources: src/Slack/BlockKit/Composites/TextObject.php1-67

---

Composite Objects

Composites are sophisticated objects that bundle multiple elements to create complex interactive components. They implement the ObjectContract interface but contain multiple child objects.

ConfirmObject

The ConfirmObject class creates confirmation dialogs that appear when users interact with dangerous or important actions. These dialogs require explicit user confirmation before proceeding.

Component Structure

Diagram: ConfirmObject Composition

Properties

Property	Type	Max Length	Description
$title	PlainTextOnlyTextObject	100 chars	Dialog title text
$text	TextObject	300 chars	Explanatory text in dialog body
$confirm	PlainTextOnlyTextObject	30 chars	Confirmation button label
$deny	PlainTextOnlyTextObject	30 chars	Cancel button label
$style	?string	N/A	Visual style: 'danger', 'primary', or null

src/Slack/BlockKit/Composites/ConfirmObject.php10-47

Constructor and Defaults

The constructor initializes sensible defaults for all required fields: src/Slack/BlockKit/Composites/ConfirmObject.php52-58

Configuration Methods

Each method returns the created text object, allowing immediate chaining for further configuration:

title(string $title): PlainTextOnlyTextObject src/Slack/BlockKit/Composites/ConfirmObject.php63-68

Sets the dialog title. Returns the created PlainTextOnlyTextObject for further customization.

text(string $text): TextObject src/Slack/BlockKit/Composites/ConfirmObject.php73-78

Sets the explanatory text. Returns a TextObject that can be configured with ->markdown() or ->verbatim().

confirm(string $label): PlainTextOnlyTextObject src/Slack/BlockKit/Composites/ConfirmObject.php83-88

Sets the confirmation button label.

deny(string $label): PlainTextOnlyTextObject src/Slack/BlockKit/Composites/ConfirmObject.php93-98

Sets the cancel button label.

danger(): static src/Slack/BlockKit/Composites/ConfirmObject.php103-108

Marks the confirmation dialog as dangerous, displaying the confirm button with red styling on desktop or red text on mobile.

Fluent Configuration Pattern

Diagram: ConfirmObject Fluent Configuration

Serialization

The toArray() method src/Slack/BlockKit/Composites/ConfirmObject.php113-126 produces the Slack API format:

The style field is only included if explicitly set via the danger() method.

Sources: src/Slack/BlockKit/Composites/ConfirmObject.php1-127

---

Object Contract Implementation

All elements and composites implement the ObjectContract interface, which defines a single method:

toArray(): array

This method converts the object to an associative array representation conforming to Slack's Block Kit JSON structure. The contract ensures consistent serialization across all Block Kit components.

Implementation Pattern

All three classes follow this pattern: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php51-62 src/Slack/BlockKit/Composites/TextObject.php50-66 src/Slack/BlockKit/Composites/ConfirmObject.php113-126

1. Build required fields array
2. Build optional fields array using array_filter() to exclude null values
3. Merge arrays with array_merge()
4. Return final array

This ensures the serialized output only contains fields that have been explicitly set, conforming to Slack's API requirements.

Sources: src/Contracts/Slack/ObjectContract.php (referenced but not provided), src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php51-62 src/Slack/BlockKit/Composites/TextObject.php50-66 src/Slack/BlockKit/Composites/ConfirmObject.php113-126

---

Usage in Block Kit Context

Elements and composites are not used in isolation. They are embedded within blocks to create complete message structures.

Typical Usage Flow

Diagram: Elements in Block Context

Example Construction Pattern

While this document does not show complete code examples, the typical construction flow is:

1. Create a SlackMessage instance
2. Add a block (e.g., ActionsBlock)
3. Within the block, add elements (e.g., ButtonElement)
4. Elements use TextObject for labels and content
5. Elements may optionally attach a ConfirmObject for confirmation dialogs

The TextObject is used in two contexts:

• As standalone content in blocks (section text, context text)
• As labels and descriptive text within interactive elements

The ConfirmObject is attached to interactive elements that require user confirmation before execution.

Sources: src/Slack/BlockKit/Composites/ConfirmObject.php1-127 src/Slack/BlockKit/Composites/TextObject.php1-67

---

Length Constraints

All text objects enforce Slack's API length constraints to prevent API errors. These constraints are enforced at construction time:

Component	Property	Max Length	Enforcement Location
PlainTextOnlyTextObject	General text	3000 chars	Constructor src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php25-36
ConfirmObject	Title	100 chars	title() method src/Slack/BlockKit/Composites/ConfirmObject.php65
ConfirmObject	Text	300 chars	text() method src/Slack/BlockKit/Composites/ConfirmObject.php75
ConfirmObject	Confirm button	30 chars	confirm() method src/Slack/BlockKit/Composites/ConfirmObject.php85
ConfirmObject	Deny button	30 chars	deny() method src/Slack/BlockKit/Composites/ConfirmObject.php95

When text exceeds the maximum length, it is automatically truncated with '...' appended: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php31-33

When text is below the minimum length (default 1 character), an InvalidArgumentException is thrown: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php27-29

Sources: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php25-36 src/Slack/BlockKit/Composites/ConfirmObject.php63-98

---

Summary

Class	Extends	Key Features	Primary Use Case
PlainTextOnlyTextObject	-	Plain text, emoji escaping, length validation	Button labels, simple text
TextObject	PlainTextOnlyTextObject	Markdown support, verbatim mode	Formatted content, rich text
ConfirmObject	-	Multi-field composite, danger styling	Confirmation dialogs for actions

These components form the foundation of the Block Kit message construction system, providing type-safe, validated objects that serialize correctly to Slack's API format.

Sources: src/Slack/BlockKit/Composites/PlainTextOnlyTextObject.php1-63 src/Slack/BlockKit/Composites/TextObject.php1-67 src/Slack/BlockKit/Composites/ConfirmObject.php1-127