Top » JSX components for Block Kit » Block elements
Slack provides some block elements that may include in layout blocks. e.g. interactive components to exchange information with Slack app.
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>
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 fromprimary
anddanger
.confirm
(optional):<Confirm>
element to show confirmation dialog. If<Confirm>
has not definedstyle
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>
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 whenmultiple
is enabled.confirm
(optional):<Confirm>
element to show confirmation dialog.
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 inActions
block. So jsx-slack throws error if you're trying to usemultiple
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>
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.
Define an item for <Select>
. <option>
intrinsic HTML element works as well.
value
(required): A string value to send to Slack App when choose item.
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>
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>
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 whenmultiple
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.
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.
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.
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.
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 whenmultiple
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.
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.
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 whenmultiple
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 channelprivate
: Private channelim
: Direct messagempim
: 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.
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 extraresponse_urls
field to theview_submission
event callback, for responding into selected channel via unique URL entrypoint. This is only available in modal's input component and cannot coexist withmultiple
prop.
A select menu with options consisted of public channels in the current workspace.
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 whenmultiple
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.
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 extraresponse_urls
field to theview_submission
event callback, for responding into selected channel via unique URL entrypoint. This is only available in modal's input component and cannot coexist withmultiple
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>
name
/actionId
(optional): An identifier for the action.confirm
(optional):<Confirm>
element to show confirmation dialog when clicked menu item.
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>
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 allowsYYYY-MM-DD
formatted string, UNIX timestamp in millisecond, and JavaScriptDate
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>
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>
name
/actionId
(optional): An identifier for the action.values
(optional): An array of value for initially selected checkboxes. They must match tovalue
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>
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.
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.
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 followingvalues
property in the parent<CheckboxGroup>
.
<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>
name
/actionId
(optional): An identifier for the action.value
(optional): A value for initially selected option. It must match tovalue
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>
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.
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.
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>
.
<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.
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>
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.
verbatim
: (optional): A boolean prop whether to disable automatic parsing for links, conversation names, and mentions by Slack.
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>
/<input>
<Textarea>
/<textarea>
<Select>
/<select>
<ExternalSelect>
<UsersSelect>
<ConversationsSelect>
<ChannelsSelect>
<DatePicker>
<CheckboxGroup>
<RadioButtonGroup>
<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>
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.
<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.
type
(required): Must behidden
.name
(required): The name of hidden value.value
(required): A value to store into modal. It must be a serializable value to JSON.
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">
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.
type
(required): Must besubmit
.value
(required): A string of submit button for the current modal. (24 characters maximum)
<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.
It's exactly same as <Input>
component, except type
prop.