Reference

Our reference for the ContentKit covers all the objects you will receive and respond with, alongside all the components you can use in order to render the UI for your integrations.
If you want to learn more about the ContentKit itself, alongside the different types of requests we make in order to make these work, please take a look at our introduction.
Components
block
Top level component for a custom block.
JSON
JSX
{
    "type": "block",
    "children": [
        ...
    ]
}
<block>
    ...
</block>
Props
Type
Description
children
Array<Block>
(Required) Content to display in the block
button
Interactive pressable button, triggering a component action when clicked.
JSON
JSX
Examples
{
    "type": "button",
    "label": "Click me",
    "onPress": { "type": "something" }
}
<button label="Click me" onPress={{ type: 'something' }} />
Basic button:
{
    "type": "button",
    "label": "Click me",
    "onPress": { "type": "something" }
}
With an icon:
{
    "type": "button",
    "label": "Click me",
    "icon": "maximize",
    "onPress": { "type": "something" }
}
With a tooltip:
{
    "type": "button",
    "label": "Click me",
    "tooltip": "More text here",
    "onPress": { "type": "something" }
}
With a confirm modal:
{
    "type": "button",
    "label": "Click me",
    "confirm": {
        "title": "Confirm the action",
        "text": "Help text here",
        "confirm": "Ok"
    },
    "onPress": { "type": "something" }
}
Props
Type
Description
label
string
(Required) Text displayed in the button
onPress
Action
(Required) Action to trigger when the button is pressed
style
'primary' | 'secondary' | 'danger'
Visual style for the button
tooltip
string
Text displayed in an hovering tooltip
icon
Icon
Visual icon to display on the start of the button
confirm
object
Modal to display to ask the user to confirm the action before execution
confirm.title
string
(Required) Title for the confirmation modal
confirm.text
string
(Required) Content of the confirmation modal
confirm.confirm
string
(Required) Label for the confirmation button
confirm.style
'primary' | 'danger'
Content of the confirmation modal
box
JSON
JSX
{
    "type": "box",
    "style": "card",
    "children": [
        ...
    ]
}
<box style="card">
    ...
</box>
Props
Type
Description
children
Array<Block> | Array<Inline>
(Required) Content to display in the block
style
'card' | 'secondary' | 'default'
Visual style for the box.
vstack
Flex layout element to render a vertical stack of elements. Use spacer, divider, and box to complete the layout.
JSON
JSX
Examples
{
    "type": "vstack",
    "align": "start",
    "children": [
        ...
    ]
}
<vstack style="start">
    ...
</vstack>
Basic vertical stack:
{
    "type": "vstack",
    "children": [
        { "type": "box", "children": [ { "type": "text", "children": ["Hello"] } ] },
        { "type": "box", "children": [ { "type": "text", "children": ["World"] } ] }
    ]
}
with align:
{
    "type": "vstack",
    "align": "center",
    "children": [
        { "type": "box", "children": [ { "type": "text", "children": ["Hello"] } ] },
        { "type": "box", "children": [ { "type": "text", "children": ["And a long text"] } ] }
    ]
}
Props
Type
Description
children
Array<Block>
(Required) Content to display in the stack
align
'start' | 'center' | 'end'
Horizontal alignment of the elements in the stack
hstack
Flex layout element to render an horizontal stack of elements. Use spacer, divider, and box to complete the layout.
JSON
JSX
Examples
{
    "type": "hstack",
    "align": "start",
    "children": [
        ...
    ]
}
<hstack style="start">
    ...
</hstack>
Basic horizontal stack:
{
    "type": "hstack",
    "children": [
        { "type": "box", "children": [ { "type": "text", "children": ["Hello"] } ] },
        { "type": "box", "children": [ { "type": "text", "children": ["World"] } ] }
    ]
}
with align:
{
    "type": "hstack",
    "align": "center",
    "children": [
        { "type": "box", "children": [ { "type": "text", "children": ["Hello"] } ] },
        { "type": "box", "children": [ { "type": "text", "children": ["And a long text"] } ] }
    ]
}
Props
Type
Description
children
Array<Block>
(Required) Content to display in the stack
align
'start' | 'center' | 'end'
Vertical alignment of the elements in the stack
spacer
A flexible space that expands along the major axis of its containing stack layout, or on both axes if not contained in a stack.
JSON
JSX
{
    "type": "spacer"
}
<spacer />
divider
A visual delimiter between 2 elements of a containing stack layout.
JSON
JSX
{
    "type": "divider"
}
<divider />
Props
Type
Description
style
"default" | "line"
Visual style for the divider.
size
"medium" | "small" | "large"
Spacing of the divider (default to medium).
text
The text element is used for rendering blocks of text with formatting.
JSON
JSX
Examples
{
    "type": "text",
    "children": [
        "Hello ",
        {
            "type": "text",
            "children": ["World"],
            "style": "bold"
        }
    ]
}
<text>
    Hello <text style="bold">World</text>
</text>
Basic text:
{
    "type": "text",
    "children": ["Hello"]
}
With nested formatting:
{
    "type": "text",
    "children": [
        "Hello ",
        {
            "type": "text",
            "style": "bold",
            "children": ["World"]
        }
    ]
}
Props
Type
Description
children
Array<string | Text>
(Required) Content of the text element.
style
"bold" | "italic" | "strikethrough" | "code"
(Required) Style to format the text with.
codeblock
Multi-lines code blocks with syntax highlighting.
JSON
JSX
{
    "type": "codeblock",
    "content": "const variable = 10",
    "syntax": "javascript"
}
<codeblock content="const variable = 10" syntax="javascript" />
Props
Type
Description
content
string
(Required) Text content for the codeblock
syntax
string
Syntax to use for highlighting
lineNumbers
boolean | number
Control the display of the line numbers
buttons
Array<Button>
Buttons to render as an overlay in top-right corner
state
string
Editable state binding. The value of the input will be stored as a property in the state named after this ID. Passing this property automatically makes the code-block editable.
onContentChange
Action
Action dispatched when the user has edited the content of this code block. It only applies if a state is passed. Usually the action is dispatched when the user is no longer focusing the code-block.
markdown
Rich-text formatting of Markdown content.
JSON
JSX
{
    "type": "markdown",
    "content": "Hello **world**"
}
<markdown content="Hello **world**" />
Props
Type
Description
content
string
(Required) Markdown text content to render
webframe
Element to render an external URL. The frame can receive update when states are updated by defining dependencies with data (see interactivity for more details).
JSON
JSX
{
    "type": "webframe",
    "source": {
        "url": "https://www.gitbook.com"
    },
    "aspectRatio": 1.7
}
<webframe
    source={{ url: 'https://www.gitbook.com' }}
    aspectRatio={16 / 9}
    />
Props
Type
Description
source
object
(Required) Content to load in the frame
source.url
string
(Required) URL of the content to load
aspectRatio
number
(Required) Aspect-ratio (width / height) for the block
buttons
Array<Button>
Buttons to render as an overlay in top-right corner
data
Record<string, string | DynamicBinding>
States this webframe is depend on. Each state update will cause the webframe to receive a message.
textinput
An input component is used to capture text input from the end user. When an action is being dispatched to the integration, the value of the input is stored in the state value referenced by id.
JSON
JSX
Examples
{
    "type": "textinput",
    "state": "name",
    "label": "Name",
    "initialValue": "John Doe",
    "placeholder": "Enter a name"
}
<textinput
    id="name"
    label="Name"
    initialValue="John Doe"
    placeholder="Enter a name"
    />
Basic textinput:
{
    "type": "textinput",
    "state": "name",
    "label": "Name",
    "initialValue": "John Doe",
    "placeholder": "Enter a name"
}
Props
Type
Description
state
string
(Required) State binding. The value of the input will be stored as a property in the state named after this ID.
initialValue
string
Initial value of the input.
label
string
Label to display next to the input.
placeholder
string
Text that appears in the form control when it has no value set
Actions
@editor.node.updateProps
Update the properties stored on the editor node binded to the current component.
{
    "action": "@editor.node.updateProps",
    "props": {}
}
@ui.url.open
{
    "action": "@ui.url.open",
    "url": "https://www.gitbook.com"
}
@ui.modal.open
Open a component componentId with props props as an overlay modal.
{
    "action": "@ui.modal.open",
    "componentId": "myModal",
    "props": {}
}
@ui.modal.close
Close the current modal. This action should be called from within a modal component.
{
    "action": "@ui.modal.close"
}
@webframe.ready
Action to send as a message from a webframe to indicate that the webframe is ready to receive messages and updates.
{
    "action": "@webframe.ready"
}
@webframe.resize
Action to send as a message from a webframe to resize the container.
{
    "action": "@webframe.resize",
    "aspectRatio": 1.7,
    "maxHeight": 400,
    "maxWidth": 300
}
@link.unfurl
Action sent to the block when the user is pasting a matching url. See Link unfurling for more details.
{
    "action": "@link.unfurl",
    "url": "https://myapp.com/"
}

Props	Type	Description
`children`	`Array<Block>`	(Required) Content to display in the block

Props	Type	Description
`label`	`string`	(Required) Text displayed in the button
`onPress`	`Action`	(Required) Action to trigger when the button is pressed
`style`	`'primary' \| 'secondary' \| 'danger'`	Visual style for the button
`tooltip`	`string`	Text displayed in an hovering tooltip
`icon`	`Icon`	Visual icon to display on the start of the button
`confirm`	`object`	Modal to display to ask the user to confirm the action before execution
`confirm.title`	`string`	(Required) Title for the confirmation modal
`confirm.text`	`string`	(Required) Content of the confirmation modal
`confirm.confirm`	`string`	(Required) Label for the confirmation button
`confirm.style`	`'primary' \| 'danger'`	Content of the confirmation modal

Props	Type	Description
`children`	`Array<Block> \| Array<Inline>`	(Required) Content to display in the block
`style`	`'card' \| 'secondary' \| 'default'`	Visual style for the box.

Props	Type	Description
`children`	`Array<Block>`	(Required) Content to display in the stack
`align`	`'start' \| 'center' \| 'end'`	Horizontal alignment of the elements in the stack

Props	Type	Description
`children`	`Array<Block>`	(Required) Content to display in the stack
`align`	`'start' \| 'center' \| 'end'`	Vertical alignment of the elements in the stack

Props	Type	Description
`style`	`"default" \| "line"`	Visual style for the divider.
`size`	`"medium" \| "small" \| "large"`	Spacing of the divider (default to `medium`).

Props	Type	Description
`children`	`Array<string \| Text>`	(Required) Content of the text element.
`style`	`"bold" \| "italic" \| "strikethrough" \| "code"`	(Required) Style to format the text with.

Props	Type	Description
`content`	`string`	(Required) Text content for the codeblock
`syntax`	`string`	Syntax to use for highlighting
`lineNumbers`	`boolean \| number`	Control the display of the line numbers
`buttons`	`Array<Button>`	Buttons to render as an overlay in top-right corner
`state`	`string`	Editable state binding. The value of the input will be stored as a property in the state named after this ID. Passing this property automatically makes the code-block editable.
`onContentChange`	`Action`	Action dispatched when the user has edited the content of this code block. It only applies if a `state` is passed. Usually the action is dispatched when the user is no longer focusing the code-block.

Props	Type	Description
`content`	`string`	(Required) Markdown text content to render

Props	Type	Description
`source`	`object`	(Required) Content to load in the frame
`source.url`	`string`	(Required) URL of the content to load
`aspectRatio`	`number`	(Required) Aspect-ratio (width / height) for the block
`buttons`	`Array<Button>`	Buttons to render as an overlay in top-right corner
`data`	`Record<string, string \| DynamicBinding>`	States this webframe is depend on. Each state update will cause the webframe to receive a message.

Props	Type	Description
`state`	`string`	(Required) State binding. The value of the input will be stored as a property in the state named after this ID.
`initialValue`	`string`	Initial value of the input.
`label`	`string`	Label to display next to the input.
`placeholder`	`string`	Text that appears in the form control when it has no value set

Interactivity

Internal design

Last modified 5mo ago

Reference

Components

`block`

`button`

`box`

`vstack`

`hstack`

`spacer`

`divider`

`text`

`codeblock`

`markdown`

`webframe`

`textinput`

Actions

`@editor.node.updateProps`

`@ui.url.open`

`@webframe.ready`

`@webframe.resize`

`@link.unfurl`