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

<block>
    ...
</block>

JSON

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

<vstack style="start">
    ...
</vstack>

JSON

{
    "type": "vstack",
    "align": "start",
    "children": [
        ...
    ]
}

Examples

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

<hstack style="start">
    ...
</hstack>

JSON

{
    "type": "hstack",
    "align": "start",
    "children": [
        ...
    ]
}

Examples

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

<divider />

JSON

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

<box style="card">
    ...
</box>

JSON

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

<card title="I am a card">
    ...
</card>

JSON

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

<text>
    Hello <text style="bold">World</text>
</text>

JSON

{
    "type": "text",
    "children": [
        "Hello ",
        {
            "type": "text",
            "children": ["World"],
            "style": "bold"
        }
    ]
}

Examples

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

<markdown content="Hello **world**" />

JSON

{
    "type": "markdown",
    "content": "Hello **world**"
}

Props	Type	Description
content*	string	Markdown text content to render

*required

Interactive

modal

Overlay modal

JSX

<modal />

JSON

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

<button label="Click me" onPress={{ type: 'something' }} />

JSON

{
    "type": "button",
    "label": "Click me",
    "onPress": { "type": "something" }
}

Examples

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

<textinput
    id="name"
    label="Name"
    initialValue="John Doe"
    placeholder="Enter a name"
    />

JSON

{
    "type": "textinput",
    "state": "name",
    "label": "Name",
    "initialValue": "John Doe",
    "placeholder": "Enter a name"
}

Examples

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

<codeblock content="const variable = 10" syntax="javascript" />

JSON

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

<webframe
    source={{ url: 'https://www.gitbook.com' }}
    aspectRatio={16 / 9}
/>

JSON

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

<select state>
...
</select>

JSON

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

<switch />

JSON

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

<checkbox />

JSON

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

radio

A radio component.

JSX

<radio />

JSON

{
    "type": "radio",
}

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