raycharius/slack-block-builder

ℹ️ Block Builder was built in Kyiv, Ukraine 🇺🇦 If it has saved you time as a developer and brought value to your projects and products, we would like to ask you to consider donating to Come Back Alive to help Ukraine in its fight against Russian aggression. Every cent helps. 🙏

Maintainable code for Slack interactive messages, modals, and home tabs.

Lightweight, zero-dependency library for declaratively building Slack Block Kit UI.

View the Docs »

Quick Start Guide · Request Feature · Report Bug

Block Builder helps you keep your Slack app code for UI maintainable, testable, and reusable. It has a declarative, chainable syntax inspired by SwiftUI and is built for better UI architecture.

⚡   Features

• Declarative SwiftUI inspired syntax.
• Commonly-used UI components, such as a Paginator and Accordion.
• Inline conditional helper functions for declaratively appending or omitting UI content.
• The ability to build more complex flows using loops and conditionals.
• A printPreviewURL() method that outputs a link to preview your UI on Slack's Block Kit Builder website for easier prototyping.
• A set of helper functions for formatting text with Slack's markdown standard.
• In-depth doc site at https://blockbuilder.dev.
• Support for all current Slack Block Kit objects.
• A great TypeScript experience.
• Extensive JSDoc hints with explanations, validation rules, and quick links to full documentation.
• Zero dependencies.

🎁   Benefits

• Write three times less code.
• Build more sophisticated, elegant flows.
• Design better UI architecture for your Slack apps.
• Focus more on code in your IDE than on studying the Slack API docs.
• Easily integrate localizations into your app.

👥   Join The Community

Feedback – love it! Aside from GitHub Issues, there's a Slack channel available in the Slack Community workspace to discuss Block Builder – we'll see you there! 🙌

• Slack Community – #block-builder

💾   Installation

Block Builder requires Node.js 12 or higher, and, when using TypeScript, TypeScript 3.8 or higher.

Using NPM:

npm install --save slack-block-builder

Using Yarn:

yarn add slack-block-builder

👾   Usage

For full documentation, make sure you head over to https://blockbuilder.dev.

Importing

The functions for creating objects can be both imported directly or through an object that groups them by category.

// Importing exposed groups of objects

import { Surfaces, Blocks, Elements, Bits, Utilities } from 'slack-block-builder';

// Importing objects top-level

import { Modal, Section, Actions, Button } from 'slack-block-builder';

The same goes for importing Slack markdown helper functions:

// Importing the Md object

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

// Importing the functions top-level

import { Modal, Section, bold, link } from 'slack-block-builder';

Object Breakdown

Surfaces – Contains functions for creating modals, messages, home tabs, and workflow steps.

Blocks – Layout blocks used to organize the UI.

Elements – UI elements that are used to capture user interaction.

Bits – These are composition objects and other bits and pieces from Slack's docs. Included are Attachment, Options, OptionGroup, and ConfirmationDialog. They felt like they were deserving of their own category.

Utilities – A group of utility functions. See Utility Functions.

Md – Helper functions for formatting text with Slack's markdown. See Markdown Helpers.

Block Kit Support and Reference

Below is a list of supported objects and how to access them in Block Builder:

Creating a Simple Interactive Message

Let's take a look at how to compose an interactive message. Even though Slack now has modals, these have always been the basis for Slack apps.

Functions that return Block Kit objects have setter methods for all of the properties, but also support parameters that are passed into the constructor for properties with primitive types.

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

export default ({ channel, dangerLevel }) =>
  Message()
    .channel(channel)
    .text('Alas, my friend.')
    .blocks(
      Blocks.Section()
        .text('One does not simply walk into Slack and click a button.'),
      Blocks.Section()
        .text('At least that\'s what my friend Slackomir said :crossed_swords:'),
      Blocks.Divider(),
      Blocks.Actions()
        .elements(
          Elements.Button()
            .text('Sure One Does')
            .actionId('gotClicked')
            .danger(dangerLevel > 42), // Optional argument, defaults to 'true'
          Elements.Button()
            .text('One Does Not')
            .actionId('scaredyCat')
            .primary()))
    .asUser()
    .buildToJSON();

And now an example with using both the setter methods and passing parameters into the functions at initiation:

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

export default ({ channel, dangerLevel }) =>
  Message({ channel, text: 'Alas, my friend.' })
    .blocks(
      Blocks.Section({ text: 'One does not simply walk into Slack and click a button.' }),
      Blocks.Section({ text: 'At least that\'s what my friend Slackomir said :crossed_swords:' }),
      Blocks.Divider(),
      Blocks.Actions()
        .elements(
          Elements.Button({ text: 'Sure One Does', actionId: 'gotClicked' })
            .danger(dangerLevel > 42), // Optional argument, defaults to 'true'
          Elements.Button({ text: 'One Does Not', actionId: 'scaredyCat' })
            .primary()))
    .asUser()
    .buildToJSON();

Both of these examples render the message below. And the best part? It only took 15 lines of code, as opposed to the 44 lines of JSON generated as a result.

View Example on Slack Block Kit Builder Website

Creating a Simple Modal

Let's take a look at how modals are created. Here we'll also take a look at working with Bits and with loops, by adding options with the Array.map() method.

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

export default ({ menuOptions, selected }) =>
  Modal({ title: 'PizzaMate', submit: 'Get Fed' })
    .blocks(
      Blocks.Section({ text: 'Hey there, colleague!' }),
      Blocks.Section({ text: 'Hurray for corporate pizza! Let\'s get you fed and happy :pizza:' }),
      Blocks.Input({ label: 'What can we call you?' })
        .element(
          Elements.TextInput({ placeholder: 'Hi, my name is... (What?!) (Who?!)' })
            .actionId('name')),
      Blocks.Input({ label: 'Which floor are you on?' })
        .element(
          Elements.TextInput({ placeholder: 'HQ – Fifth Floor' })
            .actionId('floor')),
      Blocks.Input({ label: 'What\'ll you have?' })
        .element(
          Elements.StaticSelect({ placeholder: 'Choose your favorite...' })
            .actionId('item')
            .options(menuOptions
              .map((item) => Bits.Option({ text: item.name, value: item.id })))
            .initialOption(setIfTruthy(selected, Bits.Option({ text: selected.name, value: selected.id })))))
    .buildToJSON();

Both of these examples render the modal below.

View Example on Slack Block Kit Builder Website

Paginator Component

Block Builder provides a Paginator component that assists in producing paginated UI. It allows you to dictate the UI to build for each items passed in and provides to the actionId all of the data (page, perPage, totalPages, offset, totalItems ) you need to produce the right page when a user clicks the Next or Previous buttons.

Note that there is a demo app available that demonstrates how to use components.

The Paginator component supports optional customizations, such as:

nextButtonText – Used to pass in custom text for the Next button, but has a default.

previousButtonText – Used to pass in custom text for the Next button, but has a default.

pageCountText – Used to pass in custom text for the page count, accepts a function and passes the function an object with page and totalPages properties.

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 code above renders the modal below. And be sure to check out the full documentation on the Block Builder doc site for more information.

View Example on Slack Block Kit Builder Website

Accordion Component

Using the Accordion component, you can easily create a customizable accordion for your Slack app. It not only assists in building a suitable UI, but also calculates the next state and gives you access to it in the actionId of the buttons in the accordion, so that you can pass that back to your app's backend and use it to render the next state.

Note that there is a demo app available that demonstrates how to use components.

The Accordion component supports optional customizations, such as:

collapseOnExpand – Dictates whether or not multiple items can be expanded at once. When set to true, only one item will be expanded at any given time.

expandButtonText – Used to pass in custom text for the button that expands an item, but has a default.

collapseButtonText – Used to pass in custom text for the button that collapses an expanded item, but has a default.

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 || [], // In this case, the value is [1]
      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 code above renders the modal below. And be sure to check out the full documentation on the Block Builder doc site for more information.

View Example on Slack Block Kit Builder Website

Utility Functions

The Utilities object contains various utility functions for creating UI. Currently, there are two:

BlockCollection() – Accepts multiple arguments or an array of blocks and returns them in an array, in their built state.

AttachmentCollection() – Accepts multiple arguments or an array of attachments and returns them in an array, in their built state.

OptionCollection() – Accepts multiple arguments or an array of options and returns them in an array, in their built state.

OptionGroupCollection() – Accepts multiple arguments or an array of option groups and returns them in an array, in their built state.

Both BlockCollection() and AttachmentCollection() are useful when you wish to keep surface or view configuration separate from UI representation.

An example using Slack's WebClient from their SDK for Node.js:

import { BlockCollection, AttachmentCollection, Blocks } 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));

Another example where you might find BlockCollection() helpful is when unfurling links in messages:

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

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

const unfurl = ({ channel, ts, url }) => client.chat.unfurl({
  channel,
  ts,
  unfurls: { [url]: BlockCollection( /* Pass in blocks */ ) },
})
.then((response) => console.log(response))
.catch((error) => console.log(error));

Both OptionCollection() and OptionGroupCollection() come in handy when returning an array of options or option groups for select menus with external data sources, as seen in Slack's API docs:

return { options: OptionCollection( /* Pass in options */ ) };

// Or:

return { options: OptionGroupCollection( /* Pass in option groups */ ) };

Working With Inline Conditionals

There are a few helper functions available to make it easy to work with inline conditionals within your UI source code.

They can be imported separately:

import { setIfTruthy, omitIfTruthy, setIfFalsy, omitIfFalsy } from 'slack-block-builder';

Or as a part of the conditionals object:

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

Each function accepts two arguments – the first being a value that is evaluated whether it is either null, undefined, or false, and the second being the value to set or omit:

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

export default ({ groups, selectedGroup, selectedGroupMembers }) => Modal()
  .title('Edit Groups')
  .callbackId('submit-edit-groups')
  .blocks(
    Blocks.Section({ text: 'Hello! Need to edit some groups?'}),
    Blocks.Input({ label: 'Select a group to get started' })
      .dispatchAction()
      .element(
        Elements.StaticSelect({ placeholder: 'Select a group...' })
          .actionId('selectedGroup')
          .options(groups
            .map(({ name, id }) => Bits.Option({ text: name, value: id })))),
    setIfTruthy(selectedGroup, [
      Blocks.Input({ label: 'Current group members' })
        .element(
          Elements.UserMultiSelect({ placeholder: 'Select members...' })
            .actionId('groupMembers')
            .initialUsers(selectedGroupMembers))
    ]))
  .submit(setIfTruthy(selectedGroup, 'Save Changes'))
  .buildToJSON();

These functions essentially return either the value passed into as the second argument or undefined, depending on the condition. Please note that falsy is defined as null, undefined, or false. To avoid side effects, values such as 0 or '' are not considered to be falsy.

Markdown Helpers

Often you'll find that you need to format text in your messages and modals. Block Builder has helper functions available to simply that process. They are available both as members of the Md object and as top-level imports. You can find the full list of functions on the Block Builder doc site:

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

export default ({ channel, user }) => {
  const slashCommands = ['/schedule', '/cancel', '/remind', '/help'];

  return Message({ channel, text: 'Alas, my friend.' })
    .blocks(
      Blocks.Section({ text: `:wave: Hi there, ${Md.user(user)}!` }),
      Blocks.Section({ text: `${Md.italic('Sorry')}, I didn't get that. Why don't you try out some of my slash commands?` }),
      Blocks.Section({ text: `Here are some of the things that I can do:` }),
      Blocks.Section()
        .text(Md.listBullet(slashCommands
          .map((item) => Md.codeInline(item)))))
    .asUser()
    .buildToObject();
};

View Example on Slack Block Kit Builder Website

🔗   Other Useful Slack-Related Projects

Bolt for JavaScript – A simple framework for building Slack apps, developed by Slack themselves.

Node Slack SDK – A great and powerful SDK for building Slack Apps from the ground up.

🔥   Acknowledgements

Taras Neporozhniy (@korywka) - For help and ideas along the way!

Alexey Chernyshov (@ft502 on Dribbble) - For such a beautiful logo!

SlackHQ (@slackhq) - For such a wonderful product and API!

✒️   Author

Ray East (@raycharius) - Huge Fan of Slack and Block Builder Maintainer