Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
597 lines (430 sloc) 35.9 KB
Top » JSX components for Block Kit » Block elements

Block elements

Slack provides some block elements that may include in layout blocks. e.g. interactive components to exchange information with Slack app.

Interactive components

<Button>: Button element

A simple button to send action to registered Slack App, or open external URL. <button> intrinsic HTML element also works as well.

<Blocks>
  <Actions>
    <Button actionId="action" value="value" style="primary">
      Action button
    </Button>
    <Button url="https://example.com/">Link to URL</Button>
  </Actions>
</Blocks>

Props

  • name / actionId (optional): An identifier for the action.
  • value (optional): A string value to send to Slack App when clicked button.
  • url (optional): URL to load when clicked button.
  • style (optional): Select the colored button decoration from primary and danger.
  • confirm (optional): <Confirm> element to show confirmation dialog.

<Select>: Select menu with static options

A menu element with static options passed by <Option> or <Optgroup>. It has a interface similar to <select> HTML element. In fact, <select> intrinsic HTML element works as well.

<Blocks>
  <Actions>
    <Select actionId="rating" placeholder="Rate it!">
      <Option value="5">5 {':star:'.repeat(5)}</Option>
      <Option value="4">4 {':star:'.repeat(4)}</Option>
      <Option value="3">3 {':star:'.repeat(3)}</Option>
      <Option value="2">2 {':star:'.repeat(2)}</Option>
      <Option value="1">1 {':star:'.repeat(1)}</Option>
    </Select>
  </Actions>
</Blocks>

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • value (optional): A value of item to show initially. It must choose value from defined <Option> elements in children. It can pass multiple string values by array when multiple is enabled.
  • confirm (optional): <Confirm> element to show confirmation dialog.

Multiple select

By defining multiple attribute, you also can provide the selectable menu from multiple options with an appearance is similar to button or text input. The same goes for other select-like components.

<Blocks>
  <Section>
    What kind of dogs do you love? :dog:
    <Select
      actionId="dogs"
      multiple
      placeholder="Choose favorite dog(s)"
      value={['labrador', 'golden_retriver']}
    >
      <Option value="labrador">Labrador</Option>
      <Option value="german_shepherd">German Shepherd</Option>
      <Option value="golden_retriver">Golden Retriever</Option>
      <Option value="bulldog">Bulldog</Option>
    </Select>
  </Section>
</Blocks>

⚠️ Slack does not allow to place the multi-select menu in Actions block. So jsx-slack throws error if you're trying to use multiple attribute in the children of <Actions>.

Props for multiple select
  • multiple (optional): A boolean value that shows whether multiple options can be selected.
  • maxSelectedItems (optional): A maximum number of items to allow selected.

As an input component for modal

In <Modal> container, select-like components will work as the input component for modal by passing suitable props such as required label prop. Thereby it would allow natural templating like as HTML form.

<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>

The above JSX means exactly same as following usage of <Input> layout block:

<Modal title="Programming survey">
  <Input label="Language" title="Pick language you want to learn." required>
    <Select actionId="language">
      ...
    </Select>
  </Input>
</Modal>
Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<Option>: Menu item

Define an item for <Select>. <option> intrinsic HTML element works as well.

Props

  • value (required): A string value to send to Slack App when choose item.

<Optgroup>: Group of menu items

Define a group for <Select>. <optgroup> intrinsic HTML element works as well.

<Blocks>
  <Actions>
    <Select actionId="action" placeholder="Action...">
      <Optgroup label="Search with">
        <Option value="search_google">Google</Option>
        <Option value="search_bing">Bing</Option>
        <Option value="search_duckduckgo">DuckDuckGo</Option>
      </Optgroup>
      <Optgroup label="Share to">
        <Option value="share_facebook">Facebook</Option>
        <Option value="share_twitter">Twitter</Option>
      </Optgroup>
    </Select>
  </Actions>
</Blocks>

Props

  • label (required): A plain text to be shown as a group name.

<ExternalSelect>: Select menu with external data source

You should use <ExternalSelect> if you want to provide the dynamic list from external source.

It requires setup JSON entry URL in your Slack app. Learn about external source in Slack documentation.

<Blocks>
  <Actions>
    <ExternalSelect
      actionId="category"
      placeholder="Select category..."
      minQueryLength={2}
    />
  </Actions>
</Blocks>

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • initialOption (optional): An initial option exactly matched to provided options from external source. It allows raw JSON object or <Option>. It can pass multiple options by array when multiple is enabled.
  • minQueryLength (optional): A length of typed characters to begin JSON request.
  • confirm (optional): <Confirm> element to show confirmation dialog.
Props for multiple select
  • multiple (optional): A boolean value that shows whether multiple options can be selected.
  • maxSelectedItems (optional): A maximum number of items to allow selected.
Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<SelectFragment>: Generate options for external source

You would want to build not only the message but also the data source by jsx-slack. <SelectFragment> component can create JSON object for external data source usable in <ExternalSelect>.

A following is a super simple example to serve JSON for external select via express. It is using jsxslack tagged template literal.

import { jsxslack } from '@speee-js/jsx-slack'
import express from 'express'

const app = express()

app.get('/external-data-source', (req, res) => {
  res.json(jsxslack`
    <SelectFragment>
      <Option value="item-a">Item A</Option>
      <Option value="item-b">Item B</Option>
      <Option value="item-c">Item C</Option>
    </SelectFragment>
  `)
})

app.listen(80)

<UsersSelect>: Select menu with user list

A select menu with options consisted of users in the current workspace.

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • initialUser (optional): The initial user ID. It can pass multiple string values by array when multiple is enabled.
  • confirm (optional): <Confirm> element to show confirmation dialog.
Props for multiple select
  • multiple (optional): A boolean value that shows whether multiple options can be selected.
  • maxSelectedItems (optional): A maximum number of items to allow selected.
Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<ConversationsSelect>: Select menu with conversations list

A select menu with options consisted of any type of conversations in the current workspace.

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • initialConversation (optional): The initial conversation ID. It can pass multiple string values by array when multiple is enabled.
  • confirm (optional): <Confirm> element to show confirmation dialog.
Props for multiple select
  • multiple (optional): A boolean value that shows whether multiple options can be selected.
  • maxSelectedItems (optional): A maximum number of items to allow selected.
Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<ChannelsSelect>: Select menu with channel list

A select menu with options consisted of public channels in the current workspace.

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • initialChannel (optional): The initial channel ID. It can pass multiple string values by array when multiple is enabled.
  • confirm (optional): <Confirm> element to show confirmation dialog.
Props for multiple select
  • multiple (optional): A boolean value that shows whether multiple options can be selected.
  • maxSelectedItems (optional): A maximum number of items to allow selected.
Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<Overflow>: Overflow menu

An overflow menu displayed as ... can access to some hidden menu items. It must contain 1 to 5 <OverflowItem> component(s).

<Blocks>
  <Actions>
    <Overflow actionId="overflow_menu">
      <OverflowItem value="share">Share</OverflowItem>
      <OverflowItem value="reply">Reply message</OverflowItem>
      <OverflowItem url="https://example.com/">Open in browser</OverflowItem>
    </Overflow>
  </Actions>
</Blocks>

Props

  • name / actionId (optional): An identifier for the action.
  • confirm (optional): <Confirm> element to show confirmation dialog when clicked menu item.

<OverflowItem>: Menu item in overflow menu

Props

  • value (optional): A string value to send to Slack App when choose item.
  • url (optional): URL to load when clicked button.

<DatePicker>: Select date from calendar

An easy way to let the user selecting any date is using <DatePicker> component.

<Blocks>
  <Actions>
    <DatePicker actionId="date_picker" initialDate={new Date()} />
  </Actions>
</Blocks>

Props

  • name / actionId (optional): An identifier for the action.
  • placeholder (optional): A plain text to be shown at first.
  • initialDate (optional): An initially selected date. It allows YYYY-MM-DD formatted string, UNIX timestamp in millisecond, and JavaScript Date instance.
  • confirm (optional): <Confirm> element to show confirmation dialog.

As an input component for modal

<DatePicker> also will work as the input component for modal, and may place as the children of <Modal> by passing required props.

<Modal title="My App">
  <DatePicker label="Date" name="date" />
</Modal>

Props for modal's input
  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of <Input> layout block.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.

<RadioButtonGroup>: Radio button group (Only for home tab)

A container for grouping radio buttons. It provides easy control of the selected option through similar interface to <Select>.

This component is only for <Home> container.

<Home>
  <Section>
    Select the tier of our service:
    <RadioButtonGroup actionId="tier" value="free">
      <RadioButton value="free" description="$0!">
        Free
      </RadioButton>
      <RadioButton value="standard" description="$5/month + 30 days trial!">
        Standard
      </RadioButton>
      <RadioButton value="premium" description="$30/month">
        Premium
      </RadioButton>
      <RadioButton value="business" description="Please contact to support.">
        Business
      </RadioButton>
    </RadioButtonGroup>
  </Section>
</Home>

Props

  • name / actionId (optional): An identifier for the action.
  • value (optional): A value for initial selected option. It must choose value from defined <RadioButton> elements in children.
  • confirm (optional): <Confirm> element to show confirmation dialog.

<RadioButton>: Radio button

Props

  • value (required): A string value to send to Slack App when choose option.
  • description (optional): A description text for current radio button. It can see with faded color in just below main label.

Composition objects

<Confirm>: Confirmation dialog

Define confirmation dialog. Many interactive elements can open confirmation dialog when selected, by passing <Confirm> to confirm prop.

<Blocks>
  <Actions>
    <Button
      actionId="commit"
      value="value"
      confirm={
        <Confirm title="Commit your action" confirm="Yes, please" deny="Cancel">
          <b>Are you sure?</b> Please confirm your action again.
        </Confirm>
      }
    >
      Commit
    </Button>
  </Actions>
</Blocks>

You can use HTML-like formatting to the content of confirmation dialog. However, you have to be careful that Slack ignores any line breaks and the content will render just in a line.

Props

  • title (required): The title of confirmation dialog.
  • confirm (required): A text content of the button to confirm.
  • deny (required): A text content of the button to cancel.

Input components for modal

Input components are available only for <Modal>. These include a part of interactive components and dedicated components such as <Input> and <Textarea>.

All of input components must be placed as the children of <Modal>, and defining label prop is required. (for <Input> layout block)

The list of input components is following:

<Input>: Plain-text input element

<Input> component is for placing a single-line input form within <Modal>. It can place as children of <Modal> directly.

It has an interface similar to <input> HTML element and <input> intrinsic HTML element also works as well, but must be defined label prop as mentioned above.

<Modal title="My App">
  <Input label="Title" name="title" maxLength={80} required />
</Modal>

Props

  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier for <Input> layout block.
  • name / actionId (optional): A string of unique identifier for the action.
  • type (optional): text by default.
  • title/ hint (optional): Specify a helpful text appears under the element.
  • placeholder (optional): Specify a text string appears within the content of input is empty. (150 characters maximum)
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal.
  • value (optional): An initial value for plain-text input.
  • maxLength (optional): The maximum number of characters allowed for the input element. It must up to 3000 character.
  • minLength (optional): The minimum number of characters allowed for the input element.

<Input type="hidden">: Store hidden values to modal

By using <Input type="hidden">, you can assign hidden values as the private metadata JSON of modal with a familiar way in HTML form.

<Modal title="modal">
  <Input type="hidden" name="foo" value="bar" />
  <Input type="hidden" name="userId" value={123} />
  <Input type="hidden" name="data" value={[{ hidden: 'value' }]} />

  <Input name="name" label="Name" />
</Modal>

The above example indicates the same modal as following:

<Modal
  title="modal"
  privateMetadata={JSON.stringify({
    foo: 'bar',
    userId: 123,
    data: [{ hidden: 'value' }],
  })}
>
  <Input name="name" label="Name" />
</Modal>

You can use hidden values by parsing JSON stored in callbacked private_metadata from Slack.

Note

privateMetadata prop in parent <Modal> must not define when using <Input type="hidden">. <Modal> prefers privateMetadata than <Input type="hidden"> whenever it has any value in privateMetadata prop.

And please take care that the maximum length validation by Slack will still apply for stringified JSON. The value like string and array that cannot predict the length might over the limit of JSON string length easily (3000 characters).

The best practice is only storing the value of a pointer to reference data stored elsewhere. It's better not to store complex data as hidden value directly.

Props

  • type (required): Must be hidden.
  • name (required): The name of hidden value.
  • value (required): A value to store into modal. It must be a serializable value to JSON.

<Input type="submit">: Set submit button text of modal

<Input type="submit"> can set the label of submit button for the current modal. It is meaning just an alias into submit prop of <Modal>, but JSX looks like more natural HTML form.

<Modal title="Example">
  <Input name="name" label="Name" />
  <Input type="submit" value="Send" />
</Modal>

As same as <Input type="hidden">, submit prop in <Modal> must not define when using <Input type="submit">. <Modal> prefers props defined directly.

Props

  • type (required): Must be submit.
  • value (required): A string of submit button for the current modal. (24 characters maximum)

<Textarea>: Plain-text input element with multiline

<Textarea> component has very similar interface to <Input> input component. An only difference is to allow multi-line input.

<Modal title="My App">
  <Textarea
    label="Tweet"
    name="tweet"
    placeholder="What’s happening?"
    maxLength={280}
    required
  />
</Modal>

<textarea> intrinsic HTML element also works as well.

Props

It's exactly same as <Input> component, except type prop.


Top » JSX components for Block Kit » Block elements
You can’t perform that action at this time.