slack-block-builder

Block Builder uses a builder pattern inspired by SwiftUI to create maintainable code that reflects the structure of Slack Block Kit UI.

Core Concepts:

• Builders: When you instantiate an object (like a Message), you receive a builder instance. This instance provides setter methods to configure properties.
• Chaining: Setter methods return the builder instance, allowing you to chain calls together to define the object's structure.
• Instantiation: Functions used to create objects can accept a parameters object to set initial properties, but only for primitive properties. You cannot pass Blocks or Elements directly into the instantiation parameters; instead, you should use the builder's methods to maintain a declarative structure.
• Build Methods: To convert the builder into a Slack API-compatible format, you must call a build method. The most common method is buildToJSON(). Calling a build method mutates the object's properties according to Slack API specifications to produce the final output.

import { Message, Blocks } from 'slack-block-builder';

// Example of chaining methods
const myMessage = Message()
  .channel('C12345')
  .text('Hello')
  .buildToJSON();

// Example of using params and chaining
const myMessageAlt = Message({ channel: 'C12345', text: 'Hello' })
  .buildToJSON();

The Paginator component automates paginated UI. It provides nextButtonText, previousButtonText, and pageCountText (which accepts a function with { page, totalPages }). It also provides an actionId callback that receives { page, perPage, totalPages, offset, totalItems } to help you generate the correct payload for the next interaction.

import { Modal, Blocks, Elements, Paginator } from 'slack-block-builder';

export default ({ tasks, totalTasks, page, perPage }) => Modal({ title: 'Open Tasks' })
  .blocks(
    Blocks.Section({ text: 'Hi! :wave: And welcome to the FAQ section! Take a look around and if you don\'t find what you need, feel free to open an issue on GitHub.' }),
    Blocks.Section({ text: `You currently have *${totalTasks} open task(s)*:` }),
    Paginator({
      perPage,
      items: tasks,
      totalItems: totalTasks,
      page: page || 1,
      actionId: ({ page, offset }) => JSON.stringify({ action: 'render-tasks', page, offset }),
      blocksForEach: ({ item }) => [
        Blocks.Divider(),
        Blocks.Section({ text: `*${item.title}*` })
          .accessory(
            Elements.Button({ text: 'View Details' })
              .actionId('view-details')
              .value(item.id.toString())),
        Blocks.Section({ text: `*Due Date:* ${getDate(item.dueDate)}` }),
      ],
    }).getBlocks())
  .close('Done')
  .buildToJSON();

The Accordion component creates expandable/collapsible UI items. It calculates the next state for you and provides it via the actionId callback.

Key options:

• collapseOnExpand: If true, only one item can be expanded at a time.
• expandButtonText / collapseButtonText: Customizes button text.
• isExpandable: Controls visibility of the toggle button for an item.
• items: The data array.
• expandedItems: An array of currently expanded item identifiers.
• titleText: Function to render the header text.
• actionId: Function to generate the action_id for the toggle buttons.
• blocksForExpanded: Function to return the blocks shown when an item is expanded.

import { Modal, Blocks, Accordion } from 'slack-block-builder';

export default ({ faqs, expandedItems }) => Modal({ title: 'FAQ' })
  .blocks(
    Blocks.Section({ text: 'Hi! :wave: And welcome to the FAQ section! Take a look around and if you don\'t find what you need, feel free to open an issue on GitHub.'}),
    Blocks.Divider(),
    Accordion({
      items: faqs,
      expandedItems: expandedItems || [],
      collapseOnExpand: true,
      titleText: ({ item }) => `*${item.question}*`,
      actionId: ({ expandedItems }) => JSON.stringify({ action: 'render-faqs', expandedItems }),
      blocksForExpanded: ({ item }) => [
       Blocks.Section({ text: `${item.answer}` }),
      ],
    }).getBlocks())
  .close('Done')
  .buildToJSON();

The Accordion component generates a UI for expandable and collapsible content in Slack. It works by taking an array of data items and using callback functions to determine how to render titles, how to handle state transitions via action_id, and what blocks to show when an item is expanded.

Key behaviors:

• State Management: It uses the expandedItems array (an array of integers representing indexes) to track which items are currently open.
• Interactivity: When a user clicks an expand/collapse button, the actionId function generates a string that is sent to your backend. Your backend should use this string to calculate the next state and re-render the accordion.
• Single Expansion: If collapseOnExpand is set to true, expanding a new item will automatically collapse any currently expanded item.

To use it, call Accordion(params).getBlocks() to retrieve the blocks for your Slack message or modal.

import { Accordion } from 'slack-block-builder';

const accordion = Accordion(params);
const blocks = accordion.getBlocks();

While the Message object in Block Builder can handle both UI representation and message behavior configuration, you may want to keep these concerns separate in your application. Use AttachmentCollection to define attachments independently of your main block structure. This is particularly useful when integrating with the Slack WebClient, where you can pass blocks and attachments as separate top-level keys in the API payload.

import { BlockCollection, AttachmentCollection } from 'slack-block-builder';
import { WebClient } from '@slack/web-api';

const client = new WebClient(process.env.SLACK_TOKEN);

client.chat.postMessage({
  channel: 'ABCDEFG',
  text: 'Hello, my dear, sweet world!',
  blocks: BlockCollection( /* Pass in blocks */ ),
  attachments: AttachmentCollection( /* Pass in attachments */ ),
})
.then((response) => console.log(response))
.catch((error) => console.log(error));