DOCSEARCHbyAlgolia
Submit Docs

jsx-slack

repository·main·Indexed 19 days ago

https://github.com/yhatt/jsx-slack

A library for building Slack Block Kit JSON payloads using JSX syntax. It provides a maintainable way to compose messages, modals, and app home surfaces, supporting Node.js (>=14), TypeScript (>=3.7), and Deno (v1.28+). It includes a `jsxslack` tagged template literal for use without a JSX transpiler and specialized components like <Blocks>, <Modal>, <Home>, and <Escape> for handling Slack's mrkdwn formatting.

Tokens
26.6K
Snippets
82
Records
116
Agent score
67%

What's inside jsx-slack

  1. Overview of JSX components for Slack Block Kit

    main

    The jsx-slack library provides a comprehensive set of JSX components that map directly to Slack's Block Kit UI framework. These components allow you to build complex Slack interfaces (messages, modals, and home tabs) using a declarative JSX syntax instead of manually constructing large JSON objects.

    Components are organized into three main categories:

    1. Block containers: The top-level wrappers for different Slack views, such as <Blocks> for messages, <Modal> for modal dialogs, and <Home> for home tabs.
    2. Layout blocks: Structural components that define the layout of a view, including <Section>, <Divider>, <Image>, <Header>, <Actions>, <Context>, <Input>, <Video>, <File>, and <Call>.
    3. Block elements: Interactive and content-based components that live inside layout blocks. This includes:
      • Interactive components: <Button>, <Select>, <UsersSelect>, <DatePicker>, <CheckboxGroup>, etc.
      • Composition objects: <Mrkdwn> for formatted text and <Confirm> for confirmation dialogs.
      • Input components: <Input> (text/hidden/submit) and <Textarea> for user data entry.

  2. Build Slack Block Kit surfaces with JSX

    main

    You can compose different Slack surfaces using JSX components. The library provides components for:

    • Messaging: Using <Blocks>, <Section>, <Context>, <Divider>, <Actions>, and <Button>.
    • Modals: Using <Modal>, <Input>, <Textarea>, <ConversationsSelect>, and other input components.
    • App Home: Using <Home>, <Header>, <Image>, and complex interactive components like <RadioButtonGroup>.
    // Example: Messaging surface
<Blocks>
  <Section>
    <p>Enjoy building blocks!</p>
  </Section>
  <Divider />
  <Actions>
    <Button url="https://github.com/yhatt/jsx-slack">GitHub</Button>
  </Actions>
</Blocks>

  4. Use Block containers for different Slack views

    main

    Depending on where your UI is being displayed in Slack, you must use the appropriate top-level container component:

    • <Blocks>: Use this as the basic container for all message-based content.
    • <Modal>: Use this as the view container for Slack modals.
    • <Home>: Use this as the view container for the App Home tab.

  5. Best Practice: Use input components directly instead of <Input> blocks

    main

    While <Input> is available for users who want to follow the Slack API style, it is generally recommended to use input components (like <UsersSelect>, <Textarea>, etc.) directly. This allows you to write JSX templates with a more familiar HTML form style and place them directly into a <Modal>.

    <Modal title="My App">
  <Input type="text" name="subject" label="Subject" required />
  <UsersSelect
    label="User"
    title="Please select one of users."
    required
    placeholder="Choose user..."
  />
  <Textarea name="message" label="Message" maxLength={500} />
</Modal>

  6. Use Block elements for interactivity and content

    main

    Block elements are the granular components placed inside layout blocks to provide interactivity or specific content types.

    Interactive Components

    • Buttons: <Button> and <WorkflowButton> (messaging only).
    • Selection Menus: <Select> (static), <ExternalSelect> (external data), <UsersSelect>, <ChannelsSelect>, <ConversationsSelect>, and <Overflow> menus.
    • Pickers: <DatePicker>, <TimePicker>, and <DateTimePicker>.
    • Groups: <CheckboxGroup> (with <Checkbox>) and <RadioButtonGroup> (with <RadioButton>).

    Composition Objects

    • <Mrkdwn>: Used for text composition requiring Slack's mrkdwn formatting.
    • <Confirm>: Used to create confirmation dialogs.

    Input Components

    • <Input>: Standard text input. Supports type="hidden" (to store values in Modals/Home) and type="submit" (to set the submit button text in Modals).
    • <Textarea>: Multiline plain-text input.

  7. Use Input components in containers

    main

    Input components (like <Input>, <Textarea>, <Select>, etc.) are used to collect data from users.

    Rules for usage:

    • They must be placed as direct children of a container component (e.g., <Modal> or <Home>).
    • Defining a label prop is required for most input components (except for specific types like hidden or submit).

  8. Simulate lists using <ul> and <ol>

    main

    While Slack uses plain text for lists, jsx-slack allows you to use <ul> (unordered) and <ol> (ordered) tags to generate properly indented list structures.

    • <ol> supports the start and type attributes.
    • <ol> supports standard HTML ordered list types (e.g., type="I" for Roman numerals).
    • <li> supports the value attribute.

    Example structure:

    <ul>
  <li>Item A</li>
  <li>
    Item B
    <ul>
      <li>Sub item 1</li>
    </ul>
  </li>
</ul>
    <ul>
  <li>Item A</li>
  <li>
    Item B
    <ul>
      <li>Sub item 1</li>
      <li>
        Sub item 2
        <ul>
          <li>and more...</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>
    Item C
    <ol>
      <li>Ordered item 1</li>
      <li>Ordered item 2</li>
      <ol type="I">
        <li>Ordered sub item with type 1</li>
        <li>2</li>
      </ol>
    </ol>
  </li>
</ul>

  9. Use <Select> as an input component

    main

    By providing specific props like label, a <Select> component can function as an input component within a <Modal>. This allows for natural templating similar to an HTML form.

    Input Props:

    • label (required): The label string for the element.
    • id / blockId (optional): Unique identifier for the <Input> layout block.
    • title / hint (optional): Helpful text appearing under the element.
    • required (optional): Boolean; if true, the user must fill this before confirming the modal.
    • dispatchAction (optional): If true, dispatches a block_actions payload when used.
    <Modal title="Programming survey">
  <Select
    label="Language"
    name="language"
    title="Pick language you want to learn."
    required
  >
    <Option value="javascript">JavaScript</Option>
    <Option value="python">Python</Option>
    <Option value="java">Java</Option>
    <Option value="c-sharp">C#</Option>
    <Option value="php">PHP</Option>
  </Select>
</Modal>

  10. Use JSX to return real Slack JSON in v2

    main

    In jsx-slack v2, built-in components are designed to return valid Slack API JSON objects directly. This means you no longer need to wrap your JSX in the JSXSlack() function to get a serializable object. You can simply write and evaluate the JSX.

    Note: JSXSlack() is still provided for backward compatibility, but it now acts as a no-op (it just returns the passed value).

    console.log(
  <Blocks>
    <Section>
      Welcome to <b>jsx-slack v2</b>!
    </Section>
  </Blocks>,
)

  11. Use Layout blocks to structure your UI

    main

    Layout blocks define the structural arrangement of your Slack interface. Common layout components include:

    • <Section>: A section block, which can contain text and <Field> elements.
    • <Divider>: A visual divider line.
    • <Image>: An image block.
    • <Header>: A header block for titles.
    • <Actions>: An actions block for grouping interactive elements.
    • <Context>: A context block for small metadata text.
    • <Input>: An input block for grouping input elements.
    • <Video>: A video block.
    • <File>: A file block (available only for messaging).
    • <Call>: A call block (available only for messaging).

  12. How `<Escape>` handles special characters and exceptions

    main

    The <Escape> component uses Slack's date-formatting fallback mechanism to render text as plain text. However, there are specific behaviors and exceptions you should be aware of:

    1. Leading > (Blockquotes)

    Slack recognizes > or ＞ as a blockquote only at the start of a line. Because the date-formatting fallback doesn't parse HTML entities, <Escape> handles leading > by inserting an invisible soft hyphen (U+00AD) at the beginning to prevent it from being parsed as a blockquote.

    2. Hyperlink Content (<a> tags)

    Content inside an <a> tag cannot be escaped via date formatting. Instead, <Escape> replaces special characters with similar-looking Unicode characters:

    • * becomes ∗ (U+2217) or ＊ (U+FF0A)
    • _ becomes ˍ (U+02CD) or ＿ (U+2E0F)
    • ` becomes ˋ (U+02CB)
    • ~ becomes ∼ (U+223C)
    • > becomes U+00AD + >
    • ＞ becomes U+00AD + ＞

    3. Emoji Shorthand

    Special characters within valid emoji shorthand (e.g., :white_check_mark:) are not escaped. This ensures emojis continue to render correctly.