Block for Rows and Columns GRID

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

The GRID block displays data in a tabular format of "name-value" pairs with various display options. It suits property cards: request status, priority, responsible person, deadline. For free text, use the MESSAGE block.

Pass the block as an element of the attachment's BLOCKS array; the value of the GRID key is an array of elements. General attachment rules and limits are described on the Attachments in Messages ATTACH page.

Display Options

The mode is set by the DISPLAY field of each element.

  • BLOCK — each element is displayed as a separate block on a new line. Suits long values and descriptions
  • LINE — elements are displayed in a single line as cards and wrap when there is insufficient width. Suits short labels and statuses
  • ROW — two columns: NAME on the left, VALUE on the right. Suits a "field–value" property card
  • TABLE — the API accepts the value, but the web client does not display an element in this mode, and the mobile app shows it as BLOCK. Use ROW instead of TABLE

If DISPLAY is not passed or is not recognized, the element is displayed as BLOCK. For compatibility, the legacy values CARD (same as LINE) and COLUMN (same as ROW) are accepted.

Warning

Set the same DISPLAY for all elements of a single GRID block. Clients render mixed modes differently: for example, the legacy web interface takes the mode of the whole block from the first element. If you need different modes, create several GRID blocks in a row.

GRID Element Parameters

Name
type

Description

DISPLAY
string

Display format: BLOCK, LINE, ROW. Defaults to BLOCK

NAME
string

Field name. In ROW mode, it may be omitted, in which case VALUE occupies the entire width of the row

VALUE
string

Field value, supports BB codes. In ROW mode, it may be omitted, in which case NAME occupies the entire width of the row. An element with both NAME and VALUE empty is skipped, except in LINE mode

WIDTH
integer

Width of the block or column in pixels

HEIGHT
integer

Height of the block in pixels. It is retained in the attachment, but the web client ignores it

COLOR_TOKEN
string

Color token for the value: primary, secondary, alert, base. Defaults to base

COLOR
string

HEX color of the value (#RGB or #RRGGBB). Only the legacy web interface applies it; current clients use COLOR_TOKEN

LINK
string

Link for the value: an absolute http:// or https:// URL or a path from the Bitrix24 root. Makes the entire value clickable. Clickable fragments inside the value are set with BB codes in VALUE

USER_ID
integer

User ID. It is retained in the attachment, but clients do not implement navigation by it. To link to a profile, pass the path /company/personal/user/1/ in LINK

CHAT_ID
integer

Chat ID. It is retained in the attachment, but clients do not implement navigation by it

BB Codes in VALUE

VALUE supports the same set of BB codes as the MESSAGE block, with the same differences between the web client and the mobile app.

An element whose value is a mention: {"DISPLAY": "ROW", "NAME": "Assignee", "VALUE": "[USER=1]John Smith[/USER]"}.

Examples

How to Use Examples in Documentation

The examples show a single element of the BLOCKS array.

Block Representation

DISPLAY: 'BLOCK' displays elements one below the other.

Block Representation

{
            GRID: [
                {
                    NAME: 'Description',
                    VALUE: 'Implementation required to add structured objects to messages and notifications in the messenger.',
                    DISPLAY: 'BLOCK',
                    WIDTH: 250
                },
                {
                    NAME: 'Category',
                    VALUE: 'Requests',
                    DISPLAY: 'BLOCK',
                    WIDTH: 100
                }
            ]
        }
        
block = {
            "GRID": [
                {
                    "NAME": "Description",
                    "VALUE": "We need to implement the ability to add structured objects to messenger messages and notifications.",
                    "DISPLAY": "BLOCK",
                    "WIDTH": 250,
                },
                {
                    "NAME": "Category",
                    "VALUE": "Preferences",
                    "DISPLAY": "BLOCK",
                    "WIDTH": 100,
                },
            ],
        }
        
[
            'GRID' => [
                [
                    'NAME' => 'Description',
                    'VALUE' => 'Implementation required to add structured objects to messages and notifications in the messenger.',
                    'DISPLAY' => 'BLOCK',
                    'WIDTH' => 250
                ],
                [
                    'NAME' => 'Category',
                    'VALUE' => 'Requests',
                    'DISPLAY' => 'BLOCK',
                    'WIDTH' => 100
                ]
            ]
        ]

Line Representation

DISPLAY: 'LINE' displays elements in a line, wrapping to the next line when there is insufficient space.

Line Representation

In the mobile version, elements are displayed one below the other.

{
            GRID: [
                {
                    NAME: 'Priority',
                    VALUE: 'High',
                    COLOR_TOKEN: 'alert',
                    DISPLAY: 'LINE',
                    WIDTH: 250
                },
                {
                    NAME: 'Category',
                    VALUE: 'Requests',
                    DISPLAY: 'LINE'
                }
            ]
        }
        
block = {
            "GRID": [
                {
                    "NAME": "Priority",
                    "VALUE": "High",
                    "COLOR_TOKEN": "alert",
                    "DISPLAY": "LINE",
                    "WIDTH": 250,
                },
                {
                    "NAME": "Category",
                    "VALUE": "Preferences",
                    "DISPLAY": "LINE",
                },
            ],
        }
        
[
            'GRID' => [
                [
                    'NAME' => 'Priority',
                    'VALUE' => 'High',
                    'COLOR_TOKEN' => 'alert',
                    'DISPLAY' => 'LINE',
                    'WIDTH' => 250
                ],
                [
                    'NAME' => 'Category',
                    'VALUE' => 'Requests',
                    'DISPLAY' => 'LINE'
                ]
            ]
        ]

Two-Column Representation

DISPLAY: 'ROW' displays data in two columns.

Two-Column Representation

{
            GRID: [
                {
                    NAME: 'Priority',
                    VALUE: 'High',
                    DISPLAY: 'ROW'
                },
                {
                    NAME: 'Category',
                    VALUE: 'Requests',
                    DISPLAY: 'ROW'
                }
            ]
        }
        
block = {
            "GRID": [
                {
                    "NAME": "Priority",
                    "VALUE": "High",
                    "DISPLAY": "ROW",
                },
                {
                    "NAME": "Category",
                    "VALUE": "Preferences",
                    "DISPLAY": "ROW",
                },
            ],
        }
        
[
            'GRID' => [
                [
                    'NAME' => 'Priority',
                    'VALUE' => 'High',
                    'DISPLAY' => 'ROW'
                ],
                [
                    'NAME' => 'Category',
                    'VALUE' => 'Requests',
                    'DISPLAY' => 'ROW'
                ]
            ]
        ]

Continue Learning

Previous
Divider Block
Next
Images Block