Comment on page

Components

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 are divided into 3 different categories:
Layout: Components for structuring your integration
Display: Visual components for representing data and media
Interactive: Interactive components
Layout
block
Top level component for a custom block.
JSX
JSON
<block>
    ...
</block>
{
    "type": "block",
    "children": [
        ...
    ]
}
Props
Type
Description
children*
Array<Block>
Content to display in the block.
controls
Array<BlockControl>
Control menu items displayed for the block.

controls.icon
'close' |
'edit' |
'github' |
'maximize' |
'email' |
'settings' |
'search' |
'delete' |
'star' |
'warning' |
'link' |
'link-external'
The icon to display with the control
controls.label
string
The label for the control
controls.onPress
Action
Action dispatched when control is pressed. 

See Actions for more information.
controls.confirm
object
Modal object to display to ask the user to confirm the action before execution
controls.confirm.title
string
Title for the confirmation button
controls.confirm.text
string
Content for the confirmation button
controls.confirm.confirm
string
Label for the confirmation button
controls.confirm.style
"primary" | "danger"
Style for the confirmation button.
*required
​
vstack
Flex layout element to render a vertical stack of elements. Use spacer, divider, and box to complete the layout.
JSX
JSON
Examples
<vstack style="start">
    ...
</vstack>
{
    "type": "vstack",
    "align": "start",
    "children": [
        ...
    ]
}
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>
Content to display in the stack.
align
'start' | 'center' | 'end'
Horizontal alignment of the elements in the stack.
*required
​
hstack
Flex layout element to render an horizontal stack of elements. Use spacer, divider, and box to complete the layout.
JSX
JSON
Examples
<hstack style="start">
    ...
</hstack>
{
    "type": "hstack",
    "align": "start",
    "children": [
        ...
    ]
}
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>
Content to display in the stack.
align
'start' | 'center' | 'end'
Vertical alignment of the elements in the stack.
*required
divider
A visual delimiter between 2 elements of a containing stack layout.
JSX
JSON
<divider />
{
    "type": "divider"
}
Props
Type
Description
style
"default" | "line"
Visual style for the divider.
size
"medium" | "small" | "large"
Spacing of the divider (default to medium).
​
Display
box
JSX
JSON
<box style="card">
    ...
</box>
{
    "type": "box",
    "style": "card",
    "children": [
        ...
    ]
}
Props
Type
Description
children*
Array<Block> | Array<Inline>
Content to display in the block.
style
'card' | 'secondary' | 'default'
Visual style for the box.
grow
number
Specifies how much of the remaining space in the container should be assigned to the element.
*required
​
card
JSX
JSON
<card title="I am a card">
    ...
</card>
{
    "type": "card",
    "text": "I am a card",
    "children": [
        ...
    ]
}
Props
Type
Description
children
Array<Block> | Array<Inline>
Content to display in the block.
title
string
Title for the card.
hint
string
Hint for the card.
icon
'close' |
'edit' |
'github' |
'maximize' |
'email' |
'settings' |
'search' |
'delete' |
'star' |
'warning' |
'link' |
'link-external' |
Image
Icon or Image displayed with the card.
onPress
Action
Action dispatched when pressed.

See Actions for more information.
buttons
Array<Button>
Button(s) displayed in the top right corner of the card.
*required
​
text
The text element is used for rendering blocks of text with formatting.
JSX
JSON
Examples
<text>
    Hello <text style="bold">World</text>
</text>
{
    "type": "text",
    "children": [
        "Hello ",
        {
            "type": "text",
            "children": ["World"],
            "style": "bold"
        }
    ]
}
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>
Content of the text element.
style*
"bold" | "italic" | "strikethrough" | "code"
Style to format the text with.
*required
​
image
The image component allows you to use images in your integration.
JSX
<image 
    source={{
        url: "https://example.com/image.png"
    }}
    aspectRatio={16 / 9}
/>
Props
Type
Description
source*
object
Content to load in the image.
source.url*
string
URL of the image to load
aspectRatio*
number
Aspect ratio to use for the image.
*required
​
markdown
Rich-text formatting of Markdown content.
JSX
JSON
<markdown content="Hello **world**" />
{
    "type": "markdown",
    "content": "Hello **world**"
}
Props
Type
Description
content*
string
Markdown text content to render
*required
​
Interactive
modal
Overlay modal 
JSX
JSON
<modal />
{
    "type": "button",
    "label": "Click me",
    "onPress": { "type": "something" }
}
Props
Type
Description
children*
Array<Block> | Array<Inline>
Block items to display inside the modal.
title
string
Title of the modal
subtitle
string
Subtitle of the modal
size
'medium' | 'xlarge' | 'fullscreen'
Size of the modal
returnValue
object
Data passed back to the parent view when the modal is closed. These data are accessible in the @ui.modal.close action
submit
Button
Button instance that triggers an action.
*required
​
button
Interactive pressable button, triggering a component action when clicked.
JSX
JSON
Examples
<button label="Click me" onPress={{ type: 'something' }} />
{
    "type": "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
Text displayed in the button
onPress*
Action
Action to trigger when the button is pressed

See Actions for more information.
style
'primary' | 'secondary' | 'danger'
Visual style for the button
tooltip
string
Text displayed in an hovering tooltip
icon
'close' |
'edit' |
'github' |
'maximize' |
'email' |
'settings' |
'search' |
'delete' |
'star' |
'warning' |
'link' |
'link-external' 
Visual icon to display on the start of the button
confirm
object
Modal object to display to ask the user to confirm the action before execution
confirm.title*
string
Title for the confirmation modal
confirm.text*
string
Content of the confirmation modal
confirm.confirm*
string
Label for the confirmation button
confirm.style*
'primary' | 'danger'
Style of the confirmation button
*required
​
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.
JSX
JSON
Examples
<textinput
    id="name"
    label="Name"
    initialValue="John Doe"
    placeholder="Enter a name"
    />
{
    "type": "textinput",
    "state": "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
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
*required
​
codeblock
Multi-lines code blocks with syntax highlighting.
JSX
JSON
<codeblock content="const variable = 10" syntax="javascript" />
{
    "type": "codeblock",
    "content": "const variable = 10",
    "syntax": "javascript"
}
Props
Type
Description
content*
string
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.

See Actions for more information.
*required
​
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).
JSX
JSON
<webframe
    source={{ url: 'https://www.gitbook.com' }}
    aspectRatio={16 / 9}
/>
{
    "type": "webframe",
    "source": {
        "url": "https://www.gitbook.com"
    },
    "aspectRatio": 1.7
}
Props
Type
Description
source*
object
Content to load in the frame
source.url*
string
 URL of the content to load
aspectRatio*
number
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.
*required
​
select
Select item 
JSX
JSON
<select state>
...
</select>
{
    "type": "select",
}
Props
Type
Description
state*
string
State binding. The value of the input will be stored as a property in the state named after this ID.
initialValue
string | string[]
The initial value for the select component
placeholder
string
Placeholder value for the select component
multiple
boolean
Should the select accept the selection of multiple options. If true, the state will be an array.
options
Array<object>
Options for the select component
options.id
string
Unique ID for the option
options.label
string
Label for the option
options.url
string
URL for the option if using an external link
*required
​
switch
A switch component to toggle between on and off.
JSX
JSON
<switch />
{
    "type": "switch",
}
Props
Type
Description
state*
string
State binding. The value of the input will be stored as a property in the state named after this ID.
initialValue
boolean
Value to initialize the switch with.
confirm
object
Modal object to display to ask the user to confirm the action before execution
confirm.title*
string
Title for the confirmation button
confirm.text*
string
Content for the confirmation button
confirm.confirm*
string
Label for the confirmation button
confirm.style*
'primary' | 'danger'
Style for the confirmation button
*required
​
checkbox
A checkbox component to toggle between checked and unchecked.
JSX
JSON
<checkbox />
{
    "type": "checkbox",
}
Props
Type
Description
state*
string
State binding. The value of the input will be stored as a property in the state named after this ID.
value
string | number
Value to store in a state array when the checkbox is selected.
confirm
object

Props	Type	Description
`children`*	`Array<Block>`	Content to display in the block.
`controls`	`Array<BlockControl>`	Control menu items displayed for the block.
`controls.icon`	'close' \| 'edit' \| 'github' \| 'maximize' \| 'email' \| 'settings' \| 'search' \| 'delete' \| 'star' \| 'warning' \| 'link' \| 'link-external'	The icon to display with the control
`controls.label`	`string`	The label for the control
`controls.onPress`	`Action`	Action dispatched when control is pressed. See Actions for more information.
`controls.confirm`	`object`	Modal object to display to ask the user to confirm the action before execution
`controls.confirm.title`	`string`	Title for the confirmation button
`controls.confirm.text`	`string`	Content for the confirmation button
`controls.confirm.confirm`	`string`	Label for the confirmation button
`controls.confirm.style`	`"primary"` \| `"danger"`	Style for the confirmation button.

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<Block> \| Array<Inline>`	Content to display in the block.
`title`	`string`	Title for the card.
`hint`	`string`	Hint for the card.
`icon`	'close' \| 'edit' \| 'github' \| 'maximize' \| 'email' \| 'settings' \| 'search' \| 'delete' \| 'star' \| 'warning' \| 'link' \| 'link-external' \| Image	Icon or Image displayed with the card.
`onPress`	`Action`	Action dispatched when pressed. See Actions for more information.
`buttons`	`Array<Button>`	Button(s) displayed in the top right corner of the card.

Props	Type	Description
`children`*	`Array<Block> \| Array<Inline>`	Block items to display inside the modal.
`title`	`string`	Title of the modal
`subtitle`	`string`	Subtitle of the modal
`size`	`'medium'` \| `'xlarge'` \| `'fullscreen'`	Size of the modal
`returnValue`	`object`	Data passed back to the parent view when the modal is closed. These data are accessible in the `@ui.modal.close action`
`submit`	`Button`	Button instance that triggers an action.

Props	Type	Description
`label`*	`string`	Text displayed in the button
`onPress`*	`Action`	Action to trigger when the button is pressed See Actions for more information.
`style`	`'primary' \| 'secondary' \| 'danger'`	Visual style for the button
`tooltip`	`string`	Text displayed in an hovering tooltip
`icon`	'close' \| 'edit' \| 'github' \| 'maximize' \| 'email' \| 'settings' \| 'search' \| 'delete' \| 'star' \| 'warning' \| 'link' \| 'link-external'	Visual icon to display on the start of the button
`confirm`	`object`	Modal object to display to ask the user to confirm the action before execution
`confirm.title`*	`string`	Title for the confirmation modal
`confirm.text`*	`string`	Content of the confirmation modal
`confirm.confirm`*	`string`	Label for the confirmation button
`confirm.style`*	`'primary' \| 'danger'`	Style of the confirmation button

Components

Layout

`block`

`vstack`

`hstack`

`divider`

Display

`box`

`card`

`text`

`image`

`markdown`

Interactive

`button`

`textinput`

`codeblock`

`webframe`

`select`

`switch`

`checkbox`

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

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

Props	Type	Description
`source`*	`object`	Content to load in the image.
`source.url`*	`string`	URL of the image to load
`aspectRatio`*	`number`	Aspect ratio to use for the image.

Props	Type	Description
`state`*	`string`	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

Props	Type	Description
`content`*	`string`	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. See Actions for more information.

Props	Type	Description
`source`*	`object`	Content to load in the frame
`source.url`*	`string`	URL of the content to load
`aspectRatio`*	`number`	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.