Skip to content

Latest commit

 

History

History
895 lines (670 loc) · 55.8 KB

block-elements.md

File metadata and controls

895 lines (670 loc) · 55.8 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

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 color scheme of the button from primary and danger.
  • confirm (optional): <Confirm> element to show confirmation dialog. If <Confirm> has not defined style prop, the style for confirm button may be inherited from the assigned button.

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.

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.

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 may think want to build also the data source through jsx-slack. <SelectFragment> component can create JSON object for external data source usable in <ExternalSelect>.

<SelectFragment> JSX element is serializable to JSON directly as same as container components.

Example

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)

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.

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.
  • include (optional): An array of the kind or a string of space-separated kinds, to indicate which kind of conversation types are included in list. By default, all conversation types are included. (experimental)
    • public: Public channel
    • private: Private channel
    • im: Direct message
    • mpim: Group direct message
  • excludeExternalSharedChannels (optional): A boolean value whether to exclude external shared channels from conversations list. (experimental)
  • excludeBotUsers (optional): A boolean value whether to exclude bot users from conversations list. (experimental)
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.
  • responseUrlEnabled (optional): A boolean prop whether include extra response_urls field to the view_submission event callback, for responding into selected channel via unique URL entrypoint. This is only available in modal's input component and cannot coexist with multiple prop.

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.
  • responseUrlEnabled (optional): A boolean prop whether include extra response_urls field to the view_submission event callback, for responding into selected channel via unique URL entrypoint. This is only available in modal's input component and cannot coexist with multiple prop.

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.

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.

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

<CheckboxGroup>: Checkbox group (Only for modal and home tab)

A container for grouping checkboxes. This component is only for <Modal> and <Home> container. It cannot use in <Blocks> container for messaging.

<Home>
  <Section>
    <b>ToDo List</b>
    <CheckboxGroup actionId="todo">
      <Checkbox value="xxx-0001">
        <b>Learn about Slack app</b> (
        <time datetime={new Date(2020, 1, 24)}>{'{date}'}</time>)
        <small>
          <i>
            XXX-0001: <b>High</b>
          </i>
        </small>
      </Checkbox>
      <Checkbox value="xxx-0002">
        <b>Learn about jsx-slack</b> (
        <time datetime={new Date(2020, 1, 27)}>{'{date}'}</time>)
        <small>
          <i>
            XXX-0002: <b>Medium</b>
          </i>
        </small>
      </Checkbox>
      <Checkbox value="xxx-0003" checked>
        <s>
          <b>Prepare development environment</b> (
          <time datetime={new Date(2020, 1, 21)}>{'{date}'}</time>)
        </s>
        <small>
          <i>
            XXX-0003: <b>Medium</b>
          </i>
        </small>
      </Checkbox>
    </CheckboxGroup>
  </Section>
</Home>

Props

  • name / actionId (optional): An identifier for the action.
  • values (optional): An array of value for initially selected checkboxes. They must match to value property in <Checkbox> elements in children.
  • confirm (optional): <Confirm> element to show confirmation dialog.
<Modal title="Quick survey">
  <CheckboxGroup
    id="foods"
    name="foods"
    label="What do you want to eat for the party in this Friday?"
    required
  >
    <Checkbox value="burger">Burger :hamburger:</Checkbox>
    <Checkbox value="pizza">Pizza :pizza:</Checkbox>
    <Checkbox value="taco">Tex-Mex taco :taco:</Checkbox>
    <Checkbox value="sushi">Sushi :sushi:</Checkbox>
    <Checkbox value="others">
      Others
      <small>
        <i>Let me know in the below form.</i>
      </small>
    </Checkbox>
  </CheckboxGroup>
  <Input type="text" id="others" name="others" label="What do you want?" />
</Modal>

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

<Checkbox>: Checkbox

A checkbox item. It must place in the children of <CheckboxGroup>.

It supports raw mrkdwn format / HTML-like formatting in the both of contents and description property.

<Checkbox
  value="checkbox"
  description={
    <Fragment>
      XXX-1234 - <i>by Yuki Hattori</i>
    </Fragment>
  }
>
  <b>Checkbox item</b>: foobar
</Checkbox>

ℹ️ Links and mentions through <a> tag will be ignored by Slack.

Props

  • value (required): A string value to send to Slack App when choosing the checkbox.
  • description (optional): A description string or JSX element for the current checkbox. It can see with faded color just below the main label. <Checkbox> prefers this prop than redirection by <small>.
  • checked (optional): A boolean value indicating the initial state of the checkbox. If it's not defined, the initial state is following values property in the parent <CheckboxGroup>.

Redirect <small> into description

<Checkbox> allows <small> element for ergonomic templating, to redirect the content into description when description prop is not defined.

A below checkbox is meaning exactly the same as an example shown earlier.

<Checkbox value="checkbox">
  <b>Checkbox item</b>: foobar
  <small>
    XXX-1234 - <i>by Yuki Hattori</i>
  </small>
</Checkbox>

<RadioButtonGroup>: Radio button group (Only for modal and 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 <Modal> and <Home> container. It cannot use in <Blocks> container for messaging.

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

Props

  • name / actionId (optional): An identifier for the action.
  • value (optional): A value for initially selected option. It must match to value property in one of <RadioButton> elements in children.
  • confirm (optional): <Confirm> element to show confirmation dialog.

In <Modal> container, <RadioButtonGroup> can place as <Modal>'s direct child by passing label prop as same as the input component for modal.

<Modal title="Preferences" close="Cancel">
  <RadioButtonGroup
    label="Notifications"
    id="notifications"
    name="notifications"
    title="Setting a frequency of notifications by app."
    value="all"
    required
  >
    <RadioButton value="all">
      All events
      <small>Notify all received events every time.</small>
    </RadioButton>
    <RadioButton value="summary">
      Daily summary
      <small>Send a daily summary at AM 9:30 every day.</small>
    </RadioButton>
    <RadioButton value="off">Off</RadioButton>
  </RadioButtonGroup>
  <Input type="submit" value="OK" />
</Modal>

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

<RadioButton>: Radio button

An item of the radio button. It must place in the children of <RadioButtonGroup>.

It supports raw mrkdwn format / HTML-like formatting in the both of contents and description property.

<RadioButton value="radio" description={<i>Description</i>}>
  <b>Radio button</b>
</RadioButton>

ℹ️ Links and mentions through <a> tag will be ignored by Slack.

Props

  • value (required): A string value to send to Slack App when choosing the radio button.
  • description (optional): A description string or JSX element for the current radio button. It can see with faded color just below the main label. <RadioButton> prefers this prop than redirection by <small>.

Redirect <small> into description

<RadioButton> allows <small> element for ergonomic templating, to redirect the text content into description when description prop is not defined.

A below radio button is meaning exactly the same as an example shown earlier.

<RadioButton value="radio">
  <b>Radio button</b>
  <small>
    <i>Description</i>
  </small>
</RadioButton>

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 (optional): The title of confirmation dialog.
  • confirm (optional): A text content of the button to confirm. Slack would use the default localized label if not defined.
  • deny (optional): A text content of the button to cancel. Slack would use the default localized label if not defined.
  • style (optional): Select the color scheme of the confirm button. When not defined, jsx-slack may inherit a value from assigned component such as <Button>.
    • primary: Green button on desktop, and blue text on mobile. (Slack's default if not defined)
    • danger: Red button on desktop, and red text on mobile.

<Mrkdwn>, is a component for text composition object, can use as a child of components which support HTML-like formatting. Typically it would be used when needed to set verbatim property explicitly.

Setting verbatim to false will tell Slack to auto-convert links, conversation names, and certain mentions to be linkified and automatically parsed. If verbatim set to true Slack will skip any preprocessing.

<Blocks>
  {/* Section block */}
  <Section>
    <Mrkdwn verbatim={false}>https://example.com/</Mrkdwn>
  </Section>

  {/* Section block with fields */}
  <Section>
    <Field>
      <Mrkdwn verbatim={false}>#general</Mrkdwn>
    </Field>
  </Section>

  {/* Context block */}
  <Context>
    <Mrkdwn verbatim={false}>@here</Mrkdwn>
    Hello!
  </Context>

  {/* Confirm composition object */}
  <Actions>
    <Button
      confirm={
        <Confirm title="Commit your action" confirm="Yes, please" deny="Cancel">
          <Mrkdwn verbatim={false}>
            <b>@foobar</b> Are you sure?
          </Mrkdwn>
        </Confirm>
      }
    >
      Button
    </Button>
  </Actions>
</Blocks>

Note

Slack recommends disabling automatic parsing on text composition components and they have made it clear that they might deprecate this feature in the future. More information can be found here.

jsx-slack will disable automatic parsing by default even if you were not used <Mrkdwn> specifically. If possible, we recommend never to use <Mrkdwn> in Slack app created newly with jsx-slack.

Props

  • verbatim: (optional): A boolean prop whether to disable automatic parsing for links, conversation names, and mentions by Slack.

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

<Modal> prefers the string defined in privateMetadata prop directly than <Input type="hidden">.

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.

Custom transformer

If you want to store hidden values by own way, you can use a custom transformer by passing function to privateMetadata prop in the parent <Modal>.

<Modal
  title="test"
  privateMetadata={(hidden) => hidden && new URLSearchParams(hidden).toString()}
>
  <Input type="hidden" name="A" value="foobar" />
  <Input type="hidden" name="B" value={123} />
  <Input type="hidden" name="C" value={true} />
</Modal>

In this example, the value of private_metadata field in returned payload would be A=foobar&B=123&C=true by transformation using URLSearchParams instead of JSON.stringify.

The transformer takes an argument: JSON object of hidden values or undefined when there was no hidden values. It must return the transformed string, or undefined if won't assign private metadata.

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

submit prop in <Modal> must not define when using <Input type="submit">. <Modal> prefers the prop 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