Skip to content

Latest commit

 

History

History
319 lines (232 loc) · 14.9 KB

layout-blocks.md

File metadata and controls

319 lines (232 loc) · 14.9 KB
Raw
Top » JSX components for Block Kit » Layout blocks

Layout blocks

Layout blocks are a series of basic blocks defined by Slack Block Kit.

All of these blocks can use as the children of all block containers, unless there is specific requirements such as <File> or <Call>.

<Section>: Section Block

Display a simple text message. You have to specify the content as children. It allows formatting with HTML-like elements.

<section> intrinsic HTML element works as well.

<Blocks>
  <Section>
    <p>Hello, world!</p>
  </Section>
</Blocks>

Props

  • id / blockId (optional): A string of unique identifier of block.

Accessory

A one of accessory component may include as the children of <Section>. The defined element will show in side-by-side or just below of text.

<Blocks>
  <Section>
    You can add an image next to text in this block. :point_right:
    <Image src="https://placekitten.com/256/256" alt="Accessory image" />
  </Section>
</Blocks>

Accessory components

<Field>: Fields for section block

In addition the text content, the section block also can use 2 columns texts called fields. In jsx-slack, you can define field by <Field> component in <Section> block.

<Blocks>
  <Section>
    About this repository:
    <Field>
      <b>Name</b>
      <br />
      yhatt/jsx-slack
    </Field>
    <Field>
      <b>Maintainer</b>
      <br />
      Yuki Hattori
    </Field>
    <Image src="https://github.com/yhatt.png" alt="yhatt" />
  </Section>
</Blocks>

ℹ️ Contents of <Field> would be placed after the main text contents even if placed them anywhere.

<Divider>: Divider Block

Just a divider. <hr> intrinsic HTML element works as well.

<Blocks>
  <Divider />
</Blocks>

Props

  • id / blockId (optional): A string of unique identifier of block.

<Image>: Image Block

Display an image block. It has well-known props like <img> HTML element. In fact, <img> intrinsic HTML element works as well.

<Blocks>
  <Image src="https://placekitten.com/500/500" alt="So cute kitten." />
</Blocks>

Props

  • src (required): The URL of the image.
  • alt (required): A plain-text summary of the image.
  • title (optional): An optional title for the image.
  • id / blockId (optional): A string of unique identifier of block.

<Header>: Header Block

Display a plain text in a larger and bold font. The same name <header> intrinsic HTML element works as well.

<Blocks>
  <Header>Heads up!</Header>
</Blocks>

Please be aware that header layout block only accepts the plain text for now. <br /> will work but most other HTML-like elements for styling would not work.

Props

  • id / blockId (optional): A string of unique identifier of block.

<Actions>: Actions Block

A block to hold interactive components provided by block elements. Slack allows a maximum of 25 interactive elements in <Actions> (But recommends to place up to 5 elements).

Props

  • id / blockId (optional): A string of unique identifier of block.

<Context>: Context Block

Display message context. It allows mixed contents consisted of texts and <Image> components or <img> tags.

<Blocks>
  <Context>
    <img src="https://placekitten.com/100/100" alt="Kitten" />
    A kitten and
    <img src="https://placekitten.com/100/100" alt="Kitten" />
    more kitten.
  </Context>
</Blocks>

Text contents will merge in pertinent mrkdwn elements automatically, but they also may divide clearly by using <span> HTML intrinsic element (or <Mrkdwn> component for text composition object).

<Blocks>
  <Context>
    <span>
      ◤<br />◤<br />◤
    </span>
    <span>
      ◤<br />◤
    </span>
    <span>◤</span>
    multiple mrkdwns
  </Context>
</Blocks>

⚠️ Slack restricts the number of elements consisted of text contents and images up to 10. jsx-slack throws an error if the number of generated elements is going over the limit.

Props

  • id / blockId (optional): A string of unique identifier of block.

<Input>: Input Block

Display one of interactive components for input to collect information from users.

If you want to use <Input> as layout block, you have to place one of available interactive components as a child.

<Modal title="Register" submit="OK" close="Cancel">
  <Input label="User" title="Please select one of users." required>
    <UsersSelect placeholder="Choose user..." />
  </Input>
</Modal>

Props

  • label (required): The label string for the element.
  • id / blockId (optional): A string of unique identifier of block.
  • title/ hint (optional): Specify a helpful text appears under the element. title is alias to hint prop for keeping HTML compatibility.
  • required (optional): A boolean prop to specify whether any value must be filled when user confirms modal. false by default for HTML compatibility, and notice that it is different from Slack's default.
  • dispatchAction (optional): By setting true, the input element will dispatch block_actions payload when used this.

Available interactive components

* Some components have unique properties only for input components. You cannot define them to the interactive component wrapped in <Input> layout block (TypeScript would throw error while compile).

Note

We usually recommend to use input components directly instead of using <Input> layout block. These, included <Input> and <Textarea>, can place to modal directly by passing props compatible with <Input> block, and you may write JSX template with familiar HTML form style.

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

<Input> component for layout block is provided for user that want templating with Slack API style rather than HTML style.

<Video>: Video Block

A block for embedding a video. The <video> intrinsic HTML element works as well.

<Blocks>
  <Video
    src="https://www.youtube.com/embed/RRxQQxiM7AA?feature=oembed&autoplay=1"
    alt="How to use Slack?"
    title="How to use Slack."
    poster="https://i.ytimg.com/vi/RRxQQxiM7AA/hqdefault.jpg"
    authorName="Arcado Buendia"
    description="Slack is a new way to communicate with your team. It's faster, better organized and more secure than email."
    titleUrl="https://www.youtube.com/watch?v=RRxQQxiM7AA"
    providerName="YouTube"
    providerIconUrl="https://a.slack-edge.com/80588/img/unfurl_icons/youtube.png"
  />
</Blocks>

Warning Whether the block can play the embedded video correctly is depending on the Slack app settings and the video URL. Please check out the requirements and constraints of the video layout block in Slack API documentation first.

Slack Block Kit Builder may not test and preview the video block due to the app constraints. Recommend to use your own Slack app to test.

Props

  • src / videoUrl (required): The URL to be embedded video. URL must be compatible with an embeddable iframe (<iframe src="******" />).
  • alt (required): A tooltip text for the video. It is required by Slack for accessibility.
  • title (required): A video title (200 characters maximum).
  • poster / thumbnailUrl (required): URL for the thumbnail image of the video.
  • id / blockId (optional): A string of unique identifier of block.
  • authorName (optional): The author name of the video to be displayed (50 characters maximum).
  • description (optional): The description for the video.
  • providerName (optional): The originating application name or domain of the video. (ex. YouTube)
  • providerIconUrl (optional): An image URL for the video provider icon.
  • titleUrl (optional): HTTPS URL for the hyperlink of the title text. It must correspond to the non-embeddable URL for the video.

<File>: File Block (Only for messaging)

Display a remote file that was added to Slack workspace. Learn about adding remote files in the document of Slack API. This block is only for <Blocks> container.

<Blocks>
  <File externalId="ABCD1" />
</Blocks>

Props

  • externalId (required): A string of unique ID for the file to show.
  • id / blockId (optional): A string of unique identifier of block.
  • source (optional): Override source field. At the moment, you should not take care this because only the default value remote is available.

<Call>: Call Block (Only for messaging)

Display a card of the call that was registered to Slack workspace. Learn about using the Calls API in the document of Slack API. This block is only for <Blocks> container.

<Blocks>
  <Call callId="R0123456789" />
</Blocks>

Props

  • callId (required): A string of registered call's ID.
  • id / blockId (optional): A string of unique identifier of block.
Top » JSX components for Block Kit » Layout blocks