Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

slack-block-builder

Package Overview
Dependencies
Maintainers
2
Versions
46
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

slack-block-builder

Maintainable code for interactive Slack messages, modals and home tabs. A must-have for the Slack Block Kit framework.

  • 1.8.0
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
77K
decreased by-0.31%
Maintainers
2
Weekly downloads
 
Created
Source

Logo

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

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

View the Docs »

Quick Start Guide · Request Feature · Report Bug

An example of using Block Builder


npm NPM codecov Maintainability

Block Builder helps you keep your Slack app code for UI maintainable, testable, and reusable. It has a simple builder syntax inspired by SwiftUI and lets you code the way you want to code.

:zap:   Features

  • Simple SwiftUI inspired syntax.
  • In-depth doc site at https://blockbuilder.dev.
  • Support for all current Slack Block Kit objects – Surfaces, Blocks, Elements, and Composition Objects (View Support).
  • TypeScript type definitions.
  • Super helpful JSDoc hints that include real-world explanations, Slack validation rules, and a direct link to the object's documentation on Slack's API doc site.
  • Output of the composed UI as either an object, JSON string, or array of blocks.
  • A printPreviewURL() method that outputs to the console a link to preview your UI on Slack's Block Kit Builder website.
  • Small size, with zero dependencies.

:rocket:   Coming Soon

  • Components, such as an Accordion module.
  • Configurable option to check Slack validation rules.
  • Guide for Slack apps with tips, tricks, and best practices.

:gift:   Benefits

  • Write three times less code.
  • Build more sophistocated, elegant flows.
  • Design better UI architecture (works as a template engine).
  • Focus more on experience and code in your IDE than on reading Slack API docs.
  • Code the way you want to code – not forced into any single paradigm.
  • Easily integrate localizations into your app.

:phone: Let's Talk?

Feedback – love it! Aside from GitHub Issues, there are Slack channels available in popular bot communities to discuss Block Builder – we'll see you there! :raised_hands:

:floppy_disk:   Installation

Using NPM:
npm install --save slack-block-builder
Using Yarn:
yarn add slack-block-builder

:space_invader:   Usage

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

Importing

At the top level of the library, there are a few objects exposed for import. You'll be using these to build out your UI:

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

You can also import, in place of Message, Modal or HomeTab.

Exposed Imports

Modal – Used to create a modal surface.

Message – Used to create a message surface.

HomeTab – Used to create a message surface.

Note that since you'll more often only be working with one surface per file, they are exposed individually, whereas the rest of the objects are grouped into categories.

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.

Object Support and Reference

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

NameTypeSupportAccessed Via
Home TabSurface:white_check_mark:HomeTab()
MessageSurface:white_check_mark:Message()
ModalSurface:white_check_mark:Modal()
ActionsBlock:white_check_mark:Blocks.Actions()
ContextBlock:white_check_mark:Blocks.Context()
DividerBlock:white_check_mark:Blocks.Divider()
FileBlock:white_check_mark:Blocks.File()
HeaderBlock:white_check_mark:Blocks.Header()
ImageBlock:white_check_mark:Blocks.Image()
InputBlock:white_check_mark:Blocks.Input()
SectionBlock:white_check_mark:Blocks.Section()
ButtonElement:white_check_mark:️Elements.Button()
CheckboxesElement:white_check_mark:Elements.Checkboxes()
Date PickerElement:white_check_mark:Elements.DatePicker()
Time PickerElement:white_check_mark:Elements.TimePicker()
ImageElement:white_check_mark:Elements.Img()
Overflow MenuElement:white_check_mark:Elements.OverflowMenu()
Radio ButtonsElement:white_check_mark:Elements.RadioButtons()
Plain-Text InputElement:white_check_mark:Elements.TextInput()
Select MenusElement:white_check_mark:Elements.[Type]Select()
Multi-Select MenusElement:white_check_mark:Elements.[Type]MultiSelect()
OptionComposition Object:white_check_mark:Bits.Option()
Confirm DialogComposition Object:white_check_mark:Bits.ConfirmationDialog()
Option GroupComposition Object:white_check_mark:Bits.OptionGroup()
AttachmentLegacy Feature:white_check_mark:Bits.Attachment()

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.

We can create a piece of UI using only the setter methods:

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

const myMessage = ({ channel }) => {
  return 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(),
          Elements.Button()
            .text('One Does Not')
            .actionId('scaredyCat')
            .primary()))
    .asUser()
    .buildToJSON();
};

Alternatively (and preferably), we can combine both the setter methods and the params to shorten it:

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

const myShorterMessage = ({ channel }) => {
  return 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(),
          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.

An example of using Block Builder for Messages

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. You'll see in this example that we're hardcoding the options in the select menu. There are, of course, better ways to handle that, by using the Array.map() method, but they are listed here separately to demonstrate the usage.

First, an example using just our setter methods:

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

const myModal = () => {
  return Modal()
    .title('PizzaMate')
    .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(
              Bits.Option().text(':cheese_wedge: With Cheeze').value('012'),
              Bits.Option().text(':fish: With Anchovies').value('013'),
              Bits.Option().text(':cookie: With Scooby Snacks').value('014'),
              Bits.Option().text(':beer: I Prefer Steak and Beer').value('015'))))
    .submit('Get Fed')
    .buildToJSON();
};

Alternatively (and preferably), we can combine both the setter methods and the params to shorten it:

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

const myShorterModal = () => {
  return 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(
              Bits.Option({ text: ':cheese_wedge: With Cheeze', value: '012' }),
              Bits.Option({ text: ':fish: With Anchovies', value: '013' }),
              Bits.Option({ text: ':cookie: With Scooby Snacks', value: '014' }),
              Bits.Option({ text: ':beer: I Prefer Steak and Beer', value: '015' }))))
    .buildToJSON();
};

Both of these examples render the modal below.

An example of using Block Builder for Modals

View Example on Slack Block Kit Builder Website

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.

JSX-Slack – Awesome way to create Slack Block Kit UIs using JSX.

:fire:   Acknowledgements

@bravecow Taras Neporozhniy (@bravecow) - For mentorship over the years!

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

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

:black_nib:   Author

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

Keywords

FAQs

Package last updated on 25 Nov 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc