--- title: "Rocket Chat UI Blocks Guide" slug: "blocks" description: "Learn to use UI blocks in Rocket Chat. Build secure, modular interfaces that improve collaboration and usability." updated: 2025-06-20T06:16:08Z published: 2025-06-20T06:16:08Z --- > ## Documentation Index > Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # Blocks **Blocks** are the components you will use to create the UI layout in surfaces. Within some of these blocks, you can add block elements and objects. The available blocks are: - `section` - `divider` - `image` - `actions` - `context` - `input` - `preview` We will now look at the JSON payload and more details to define each of these blocks in your apps. --- ## section A `section` is used to display text and can contain additional block elements. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `section`. | | `text` | Object{} | No | An array of text elements that should contain the following: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. - `emoji`: A boolean that indicates whether the text should display emojis or not. This field is optional. | | `fields` | Array[{}] | No | An array of text elements that should contain the following: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | | `accessory` | Object{} | No | A section can contain the following block elements: - `button` - `image` - `datepicker` - `overflow` - `static_select` | ****Example of a**`section`**block**** The following `section` block example contains a text object ```json {  type: 'section',  blockId: 'section_1',  text: {      type: 'plain_text',      text: 'lorem ipsum 🚀',      emoji: true,    },  fields: [{      type: 'plain_text',      text: 'field section'    },    {      type: 'plain_text',      text: 'field section'    }  ], accessory: { /* define any of the block elements in this object */ } } ``` The UI looks something like this: ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(116).png) With the `fields` array: ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(130).png) --- ## divider A divider is a horizontal line used to visually separate different pieces of content. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `divider`. | ****Example of a**`divider`**block**** The following example shows the `divider` block: ```json {  type: 'divider',  blockId: 'divider_1', } ``` On a message surface, the divider looks like this: ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(118).png) --- ## image Add images to make your app more appealing. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `image`. | | `imageUrl` | String | Yes | The URL of the image. | | `altText` | String | Yes | A text describing the image being displayed. | | `title` | Object{} | No | The text is displayed as the image's title. The object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. - `emoji`: A boolean that indicates whether the text should display emojis or not. This field is optional. | ****Example of an**`image`**block**** The following example shows an `image` block with a title and alternate text. ```json {  type: 'image',  blockId: 'image_1',  imageUrl: 'https://picsum.photos/200/300',  altText: 'An image',  title: {      type: 'plain_text',      text: 'lorem ipsum 🚀',      emoji: true,    } } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(119).png) --- ## actions An `actions` block contains interactive elements and can be used to provide options. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `actions`. | | `elements` | Array[{}] | Yes | A list of interactive block elements. The available options are: - `button` - `checkbox` - `datepicker` - `linear_scale` - `overflow` - `radio_button` - `static_select` - `timepicker` | ****Example of an**`actions`**block**** The following example shows an `actions` block containing a `static_select` block element. ```json {  type: 'actions',  blockId: 'actions_1',  elements: [      {           type: 'static_select',           appId: appId,           blockId: 'static_select_action_block',           actionId: 'static_select_action_1',           placeholder: {                type: 'plain_text',                text: 'Select an option'      },           options: [      {               value: 'option_1',               text: {               type: 'plain_text',               text: 'This is your first option'      }},      {           value: 'option_2',           text: {                type: 'plain_text',                text: 'This is your second option'       }}  ]} ] } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Screenshot 2024-12-12 154238.png) --- ## context You can use the `context` block to provide quick information or notifications to your users. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `context`. | | `elements` | Array[{}] | Yes | A list of block elements. Allowed elements are `plain text object` and `image element`. | ****Example of a**`context`**block**** The following example shows a `context` block with text and image elements. ```json {  type: 'context',  blockId: 'context_1',  elements: [      {            type: 'plain_text',            text: 'This is a context block'      },      {            type: 'image',            imageUrl: 'https://img.freepik.com/free-vector/rocket-background-flat-style_23-2147904992.jpg?size=338&ext=jpg&ga=GA1.1.2008272138.1726444800&semt=ais_hybrid',            altText: 'An icon of a rocket'       }] } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(121).png) --- ## input Similar to the `actions` block, an `input` block can contain elements to provide options and get information from users. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, `input`. | | `element` | Object{} | Yes | A list of interactive block elements. The available options are: - `checkbox` - `datepicker` - `linear_scale` - `plain_text_input` - `radio_button` - `static_select` - `timepicker` | | `label` | Object{} | Yes | The label for the block. The object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | ****Example of an**`input`**block**** The following example shows an `input` block with the `plain_text_input` element: ```json {     type: 'input',     label: {               type: 'plain_text',               text: 'Plain text input'      },     element: {             type: 'plain_text_input',             appId: appId,             actionId: 'plain_text_input_action_1',             blockId: 'plain_text_input_block_1',             placeholder: {             type: 'plain_text',             text: 'Enter the text input here'       }, }}, ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Screenshot 2024-12-13 123318.png) --- ## preview Previews can be used to share notices or a block of information with users. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `blockId` | String | No | A unique identifier for the block. | | `type` | String | Yes | The type of the block, in this case, the value is `preview` | | `description` | Array[{}] | Yes | The preview description object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | | `title` | Array[{}] | Yes | The preview title object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | ****Example of a**`preview`**block**** The following example shows a `preview` block: ```json {  type: 'preview',  description: [      {           type: 'plain_text',           text: 'Description of preview'       }],  title: [  {    type: 'plain_text',    text: 'Title of preview'   } ]} ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Screenshot 2024-12-13 144152.png) --- ## callout A `callout` block can be used to bring attention to specific information. **Supported surfaces**: Contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `appId`, `blockId` | String | No | See [Parameter details](/v1/docs/building-blocks#parameter-details). | | `type` | String | Yes | The type of the block, in this case, the value is `callout` | | `text` | Object{} | Yes | The text object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | | `title` | Object{} | No | The callout title object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | | `variant` | String | No | The callout style that will be displayed. The options are: - `info` - `warning` - `success` - `danger` | ****Example of a**`callout`**block**** The following example shows the callout types in a contextual bar: ```json {        type: 'callout',        text: {          type: 'plain_text',          text: 'Text of callout'        },        title: {          type: 'plain_text',          text: 'Title of callout'        },        variant: 'info'      },      {        type: 'callout',        text: {          type: 'plain_text',          text: 'Text of callout'        },        title: {          type: 'plain_text',          text: 'Title of callout'        },        variant: 'danger'      },      {        type: 'callout',        text: {          type: 'plain_text',          text: 'Text of callout'        },        title: {          type: 'plain_text',          text: 'Title of callout'        },        variant: 'success'      },      {        type: 'callout',        text: {          type: 'plain_text',          text: 'Text of callout'        },        title: {          type: 'plain_text',          text: 'Title of callout'        },        variant: 'warning' } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(126).png) --- ## tab navigation **Supported surfaces**: Contextual bars | Field | Type | Required? | Description | | --- | --- | --- | --- | | `actionId`, `appId`, `blockId` | String | Yes | See [Parameter details](/v1/docs/building-blocks#parameter-details). | | `type` | String | Yes | The type of the block, in this case, the value is `tab_navigation` | | `title` | Object{} | Yes | The tab title object should contain the following fields: - `type`: The type in which you want to enter the text. It can either be `plain_text` or `mrkdown`. - `text`: The text that you want to enter. | ****Example of a**`tab_navigation`**block**** The following example shows two tabs: ```json {        type: 'tab_navigation',        tabs: [          {            type: 'tab',            appId: appId,            blockId: 'tab_block_1',            actionId: 'tab_action_1',            title: {              type: 'plain_text',              text: 'Tab Title'            },          },          {            type: 'tab',            appId: appId,            blockId: 'tab_block_2',            actionId: 'tab_action_2',            title: {              type: 'plain_text',              text: 'Tab Title'            },          }        ] } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(128).png) --- ## conditional block A conditional block is used to specify where the blocks can be rendered. It works with the Livechat client and in the Rocket.Chat client. **Supported surfaces**: Messages, contextual bars, modals | Field | Type | Required? | Description | | --- | --- | --- | --- | | `appId`, `blockId` | String | No | See [Parameter details](/v1/docs/building-blocks#parameter-details). | | `type` | String | Yes | The type of the block, in this case, the value is `conditional` | | `render` | Array[{}] | Yes | This array contains the blocks that will be displayed. The options are: - `actions` - `callout` - `context` - `divider` - `image` - `input` - `preview` - `section` - `tab_navigation` | | `when` | Array[] | No | Determine where the blocks will be displayed. The options are `livechat` and `rocket.chat`. | ****Example of a**`conditional`**block**** The following example shows the block in a message surface: ```json {        type: 'conditional',        render: [          {            type: 'section',            text: {              type: 'plain_text',              text: 'Conditional block'            }          }        ],      when: {              engine: ['rocket.chat', 'livechat']    } } ``` ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/image(129).png) > [!NOTE] > - For more examples on using these blocks, see [Using UIKit Blocks](/using-uikit-blocks). > - See the [Parameter details](/building-blocks#parameter-details) section to learn more about the common identifiers that you may need to provide.