This section explores how to create a custom user interface using snap-kit and DevRev.

Understanding the structure

The snap-kit JSON has a top-level structure with object, body, type, and snap_kit_body fields. The snap_kit_body field contains information regarding snap-kit’s structure.

For example:

1{
2 "object": "<source_id>",
3 "body": "Giphy",
4 "type": "timeline_comment",
5 "snap_kit_body": {}
6}

Snap-kit body

The snap_kit_body field has the following properties:

  • snap_in_id: A unique identifier for the snap-kit.
  • snap_in_action_name: The name of the action this snap-kit represents.
  • body: An object that holds the actual snap-kit content in the form of snaps.

For example:

1"snap_kit_body": {
2 "snap_in_id": "<snap_in_id>",
3 "snap_in_action_name": "giphy",
4 "body": { "snaps": [] }
5}

Body

The body field contains an array of snaps. Each snap can have a type, and depending on the type, it has different properties.

Snaps

The following snap types are supported:

Base types

User interface elements

Form elements

Layout elements

Data pickers

Action payloads

Snap-kit generates payloads when a user interacts with an actionable snap. The payload is sent to the backend and can be used to perform actions. The following snaps generate payloads:

Base Payload

All actionable snaps share the same base payload structure. The base payload has the following structure:

1{
2 "type": "<type of Snap that generated the payload>",
3 "action_id": "<the action identifier of the Snap that generated the payload>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>"
6}

Base Types

Many elements share the same base properties. The base types these elements inherit from are described below.

A snap is the base type that all other snaps inherit from.

Properties

  • type (required): Type of snap
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Base interface for action components.

Action types

There are two types of action:

  • Remote action: It triggers a backend API and is handled by the backend.
  • Client action: It triggers a client-side action and is handled by the client.

Properties

  • action_id (required): An identifier for the action. It should be unique in the snap.
  • action_type (optional): Indicates whether the backend or client handles the action. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".
Inherited properties

Inherited from Snap:

  • type (required): Type of snap.
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Base interface for focusable components.

Properties

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Base interface for components that can have a placeholder.

Properties

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Base interface for components that can be disabled.

Properties

  • disabled (optional): Indicates whether the element is disabled.

Base interface for components that can be hidden.

Properties

  • hidden (optional): Indicates whether the element is hidden.

Controls how the layout is displayed. Similar to flexbox.

Properties

  • direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
  • alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
  • justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

User interface elements

A button that can be clicked to trigger an action. Works with Actions and Form blocks.

Properties

  • text (required): The text to be displayed on the button.
  • style (optional): The style of the button. Defaults to "default". Possible values: "default", "primary", "destructive".
  • value (required): The value associated with the button. It’s sent along with the interaction payload.
  • href (optional): If the button is a link, this is the URL it links to.
  • disabled (optional): Disables the input and prevents changes to the value.
  • disabled_text (optional): The text that’s shown on hover if the component is disabled.
Inherited properties

Inherited from Snap:

  • type (required): The type of the button component, should be set to "button".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action and is unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Example

Button variants are displayed in a row using the Card snap.

button

1{
2 "elements": [
3 {
4 "direction": "row",
5 "elements": [
6 {
7 "action_id": "PRIMARY",
8 "action_type": "remote",
9 "style": "primary",
10 "text": {
11 "text": "PRIMARY",
12 "type": "plain_text"
13 },
14 "type": "button",
15 "value": "PRIMARY"
16 },
17 {
18 "action_id": "SECONDARY",
19 "action_type": "remote",
20 "style": "secondary",
21 "text": {
22 "text": "SECONDARY",
23 "type": "plain_text"
24 },
25 "type": "button",
26 "value": "SECONDARY"
27 },
28 {
29 "action_id": "DESTRUCTIVE",
30 "action_type": "remote",
31 "style": "destructive",
32 "text": {
33 "text": "DESTRUCTIVE",
34 "type": "plain_text"
35 },
36 "type": "button",
37 "value": "DESTRUCTIVE"
38 },
39 {
40 "action_id": "TERTIARY",
41 "action_type": "remote",
42 "style": "tertiary",
43 "text": {
44 "text": "TERTIARY",
45 "type": "plain_text"
46 },
47 "type": "button",
48 "value": "TERTIARY"
49 },
50 {
51 "action_id": "PRIMARY",
52 "action_type": "remote",
53 "disabled": true,
54 "style": "primary",
55 "text": {
56 "text": "DISABLED",
57 "type": "plain_text"
58 },
59 "type": "button",
60 "value": "PRIMARY"
61 }
62 ],
63 "type": "actions"
64 }
65 ],
66 "type": "card"
67}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "button".

1{
2 "type": "button",
3 "action_id": "<the action identifier of the button>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<the value associated with the button>"
7}
Example payload
1{
2 "action_id": "PRIMARY",
3 "action_type": "remote",
4 "type": "button",
5 "value": "PRIMARY",
6 "timestamp": "2023-07-12T08:12:10.006Z"
7}

A divider component is used to separate blocks.

Properties

The divider component does not have any properties of its own.

Inherited properties

Inherited from Snap:

  • type (required): The type of the divider component, should be set to "divider".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

Divider is used in a form to separate a name input and a multi-select input.

divider_in_form

1{
2 "elements": [
3 {
4 "action_id": "example_form",
5 "elements": [
6 {
7 "element": {
8 "action_id": "example_name",
9 "placeholder": {
10 "text": "Enter your name",
11 "type": "plain_text"
12 },
13 "type": "plain_text_input"
14 },
15 "label": {
16 "text": "Name",
17 "type": "plain_text"
18 },
19 "type": "input_layout"
20 },
21 {
22 "type": "divider"
23 },
24 {
25 "element": {
26 "action_id": "example_preferences",
27 "options": [
28 {
29 "text": {
30 "text": "Email",
31 "type": "plain_text"
32 },
33 "value": "email"
34 },
35 {
36 "text": {
37 "text": "Slack",
38 "type": "plain_text"
39 },
40 "value": "slack"
41 },
42 {
43 "text": {
44 "text": "Other",
45 "type": "plain_text"
46 },
47 "value": "other"
48 }
49 ],
50 "type": "multi_static_select"
51 },
52 "label": {
53 "text": "Select your preferred ways of communication",
54 "type": "plain_text"
55 },
56 "type": "input_layout"
57 },
58 {
59 "element": {
60 "action_id": "example_other",
61 "type": "plain_text_input"
62 },
63 "label": {
64 "text": "Additional Notes",
65 "type": "plain_text"
66 },
67 "optional": true,
68 "type": "input_layout"
69 }
70 ],
71 "submit_action": {
72 "action_id": "example_button",
73 "style": "primary",
74 "text": {
75 "text": "Submit",
76 "type": "plain_text"
77 },
78 "type": "button",
79 "value": "SUBMIT"
80 },
81 "type": "form"
82 }
83 ],
84 "type": "card"
85}

An image block that displays an image. Works with Content blocks.

Properties

  • image_url (required): The URL of the image.
  • alt_text (required): The alt text to be displayed when the image can’t be displayed. This shouldn’t contain any markup.
  • fill_container (optional): Whether the image should stretch to fill the container while maintaining its aspect ratio.
Inherited properties

Inherited from Snap:

  • type (required): The type of the image component, should be set to "image".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

Image used in a card, with default display mode (fill_container not set).

image_default

1{
2 "elements": [
3 {
4 "alignment": "center",
5 "elements": [
6 {
7 "text": "Default image display mode: Creating a group in DevRev",
8 "type": "plain_text"
9 },
10 {
11 "alt_text": "Group creation",
12 "image_url": "https://docs.devrev.ai/_next/image?url=%2Fimg%2Fgroups.gif&w=750&q=75",
13 "type": "image"
14 }
15 ],
16 "type": "content"
17 }
18 ],
19 "type": "card"
20}

Image used in a card, with fill_container set.

image_fill

1{
2 "elements": [
3 {
4 "alignment": "center",
5 "elements": [
6 {
7 "text": "Fill container image display mode: Creating a group in DevRev",
8 "type": "plain_text"
9 },
10 {
11 "alt_text": "Group creation",
12 "image_url": "https://docs.devrev.ai/_next/image?url=%2Fimg%2Fgroups.gif&w=750&q=75",
13 "type": "image"
14 }
15 ],
16 "type": "content"
17 }
18 ],
19 "type": "card"
20}

A plain text element is used to define unformatted text.

Properties

  • text (required): The plain text content.
Inherited properties

Inherited from Snap:

  • type (required): The type of the element, should be set to "plain_text".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

plain_text

1{
2 "elements": [
3 {
4 "text": "Hello this is an example of a plain text element",
5 "type": "plain_text"
6 }
7 ]
8}

A rich text element is used to define formatted text.

Properties

  • text (required): The rich text content.
Inherited properties

Inherited from Snap:

  • type (required): The type of the element, should be set to "rich_text".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

rich_text

1{
2 "text": "# Welcome to DevRev! \n[DevRev](https://devrev.ai)",
3 "type": "rich_text"
4}

Table

A table element used to present JSON structured data.

Properties

  • rows (required): The values to be displayed in the table. The data should be provided as a JSON object, where each cell is a plaintext SnapKit component.
  • columns (required): Columns are defined as an array of objects, where each object has two parameters: an optional header and a required field key, which defines which field from rows is shown in the defined column. If a key is not used, it means that the associated data from rows will not be displayed in the table. The order of keys also defines the order in which values from rows are shown in the table.

Inherited properties

Inherited from Snap:

  • type (required): The type of the element, should be set to "table".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

table

1{
2 "elements": [
3 {
4 "columns": [
5 {
6 "header": {
7 "text": "Date",
8 "type": "plain_text"
9 },
10 "key": "date"
11 },
12 {
13 "header": {
14 "text": "Status",
15 "type": "plain_text"
16 },
17 "key": "status"
18 },
19 {
20 "header": {
21 "text": "Project Title",
22 "type": "plain_text"
23 },
24 "key": "title"
25 }
26 ],
27 "rows": [
28 {
29 "date": {
30 "text": "2024-03-04",
31 "type": "plain_text"
32 },
33 "hiddenField": {
34 "text": "Hidden value",
35 "type": "plain_text"
36 },
37 "status": {
38 "text": "Completed",
39 "type": "plain_text"
40 },
41 "title": {
42 "text": "Project A",
43 "type": "plain_text"
44 }
45 },
46 {
47 "date": {
48 "text": "2024-03-05",
49 "type": "plain_text"
50 },
51 "hiddenField": {
52 "text": "hidden",
53 "type": "plain_text"
54 },
55 "status": {
56 "text": "In Progress",
57 "type": "plain_text"
58 },
59 "title": {
60 "text": "Project B",
61 "type": "plain_text"
62 }
63 },
64 {
65 "date": {
66 "text": "2024-03-06",
67 "type": "plain_text"
68 },
69 "hiddenField": {
70 "text": "hidden",
71 "type": "plain_text"
72 },
73 "status": {
74 "text": "Pending",
75 "type": "plain_text"
76 },
77 "title": {
78 "text": "Project C",
79 "type": "plain_text"
80 }
81 }
82 ],
83 "type": "table"
84 }
85 ]
86}

Table

A table element used to present JSON structured data.

Properties

  • rows (required): The values to be displayed in the table. The data should be provided as a JSON object, where each cell is a plaintext SnapKit component.
  • columns (required): Columns are defined as an array of objects, where each object has two parameters: an optional header and a required field key, which defines which field from rows is shown in the defined column. If a key is not used, it means that the associated data from rows will not be displayed in the table. The order of keys also defines the order in which values from rows are shown in the table.

Inherited properties

Inherited from Snap:

  • type (required): The type of the element, should be set to "table".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Example

table

1{
2 "elements": [
3 {
4 "columns": [
5 {
6 "header": {
7 "text": "Date",
8 "type": "plain_text"
9 },
10 "key": "date"
11 },
12 {
13 "header": {
14 "text": "Status",
15 "type": "plain_text"
16 },
17 "key": "status"
18 },
19 {
20 "header": {
21 "text": "Project Title",
22 "type": "plain_text"
23 },
24 "key": "title"
25 }
26 ],
27 "rows": [
28 {
29 "date": {
30 "text": "2024-03-04",
31 "type": "plain_text"
32 },
33 "hiddenField": {
34 "text": "Hidden value",
35 "type": "plain_text"
36 },
37 "status": {
38 "text": "Completed",
39 "type": "plain_text"
40 },
41 "title": {
42 "text": "Project A",
43 "type": "plain_text"
44 }
45 },
46 {
47 "date": {
48 "text": "2024-03-05",
49 "type": "plain_text"
50 },
51 "hiddenField": {
52 "text": "hidden",
53 "type": "plain_text"
54 },
55 "status": {
56 "text": "In Progress",
57 "type": "plain_text"
58 },
59 "title": {
60 "text": "Project B",
61 "type": "plain_text"
62 }
63 },
64 {
65 "date": {
66 "text": "2024-03-06",
67 "type": "plain_text"
68 },
69 "hiddenField": {
70 "text": "hidden",
71 "type": "plain_text"
72 },
73 "status": {
74 "text": "Pending",
75 "type": "plain_text"
76 },
77 "title": {
78 "text": "Project C",
79 "type": "plain_text"
80 }
81 }
82 ],
83 "type": "table"
84 }
85 ]
86}

Form elements

Plain text options are a commonly shared component of different form elements. It’s used to define an option in a form element.

  • text (required): A Plain Text element representing the option.
  • value (required): A value assigned to the option.
  • description (optional): An optional Plain Text element describing the option.

A component that provides a group of checkboxes that allow a user to choose multiple items from a list of options. Works with Input Layout and Actions blocks.

Properties

  • options (required): A list of options that appears in a stack of checkboxes, of type Plain Text Option.
  • initial_options (optional): The initially selected options.
Inherited properties

Inherited from Snap:

  • type (required): The type of the checkbox group component, should be set to "checkboxes".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

checkboxes

1{
2 "elements": [
3 {
4 "action_id": "checkboxes",
5 "action_type": "remote",
6 "options": [
7 {
8 "description": {
9 "text": "Description for option 1",
10 "type": "plain_text"
11 },
12 "text": {
13 "text": "Option 1",
14 "type": "plain_text"
15 },
16 "value": "option_1"
17 },
18 {
19 "description": {
20 "text": "Description for option 1",
21 "type": "plain_text"
22 },
23 "text": {
24 "text": "Option 2",
25 "type": "plain_text"
26 },
27 "value": "option_2"
28 }
29 ],
30 "type": "checkboxes"
31 },
32 {
33 "action_id": "checkboxes",
34 "action_type": "remote",
35 "disabled": true,
36 "options": [
37 {
38 "description": {
39 "text": "Description for option 1",
40 "type": "plain_text"
41 },
42 "text": {
43 "text": "Disabled Option 1",
44 "type": "plain_text"
45 },
46 "value": "option_1"
47 },
48 {
49 "description": {
50 "text": "Description for option 1",
51 "type": "plain_text"
52 },
53 "text": {
54 "text": "Disabled Option 2",
55 "type": "plain_text"
56 },
57 "value": "option_2"
58 }
59 ],
60 "type": "checkboxes"
61 }
62 ],
63 "type": "actions"
64}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "checkboxes".

1{
2 "type": "checkboxes",
3 "action_id": "<the action identifier of the checkboxes>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<array of selected Plain Text Option objects>"]
7}
Example payload
1{
2 "action_id": "checkboxes",
3 "action_type": "remote",
4 "type": "checkboxes",
5 "value": [
6 {
7 "description": {
8 "text": "Description for option 1",
9 "type": "plain_text"
10 },
11 "text": { "text": "Option 2", "type": "plain_text" },
12 "value": "option_2"
13 }
14 ],
15 "timestamp": "2023-07-12T08:14:52.370Z"
16}

There are 4 supported input types:

  • Plain Text Input
  • Number Input
  • Email Input
  • Rich Text Input

Properties

The input component does not have any properties of its own. See specific variants below for their properties.

Inherited properties

Inherited from Snap:

  • type (required): Type of the input component. Should be set according to the input type, see below.
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Plain text input

A plain-text input, similar to the HTML <input> tag, creates a field where a user can enter freeform data. It can appear as a single-line field. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "plain_text_input".
Additional properties
  • initial_value (optional): The initial value in the input when it’s loaded.
  • multiline (optional): Indicates whether the input should allow multiple lines of text. Defaults to false.
  • min_length (optional): The minimum text length, can’t be greater than max_length.
  • max_length (optional): The maximum text length, can’t be less than min_length.
  • resize (optional): Indicates whether the input should be resizable. Defaults to false.
Example

plain_text_input

1{
2 "element": {
3 "action_id": "name",
4 "min_length": 10,
5 "placeholder": {
6 "text": "Enter your name",
7 "type": "plain_text"
8 },
9 "type": "plain_text_input"
10 },
11 "hint": {
12 "text": "Please enter your name",
13 "type": "plain_text"
14 },
15 "label": {
16 "text": "User Name",
17 "type": "plain_text"
18 },
19 "optional": true,
20 "type": "input_layout"
21}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "plain_text_input".

1{
2 "type": "plain_text_input",
3 "action_id": "<the action identifier of the plain text input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<the value of the input>"
7}
Example payload
1{
2 "type": "plain_text_input",
3 "action_id": "name",
4 "action_type": "remote",
5 "timestamp": "2023-07-12T08:17:43.887Z",
6 "value": "Chuck Norris"
7}

Number input

A number input, similar to the HTML <input> tag, creates a field where a user can enter numbers. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "number_input".
Additional properties
  • initial_value (optional): The initial value in the input when it’s loaded.
  • min_value (optional): The minimum value, can’t be greater than max_value.
  • max_value (optional): The maximum value, can’t be less than min_value.
Example

number_input

1{
2 "element": {
3 "action_id": "age",
4 "max_value": 120,
5 "min_value": 10,
6 "type": "number_input"
7 },
8 "label": {
9 "text": "Age",
10 "type": "plain_text"
11 },
12 "type": "input_layout"
13}
Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "number_input".

1{
2 "type": "number_input",
3 "action_id": "<the action identifier of the number input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<the value of the input>"
7}
Example payload
1{
2 "type": "number_input",
3 "action_id": "age",
4 "action_type": "remote",
5 "timestamp": "2023-07-12T08:17:43.887Z",
6 "value": "83"
7}

Email input

An email input, similar to the HTML <input> tag, creates a field where a user can enter email. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "email_text_input".
Additional properties
  • initial_value (optional): The initial value in the input when it’s loaded.
Example

email_input

1{
2 "element": {
3 "action_id": "email",
4 "placeholder": {
5 "text": "example@devrev.ai",
6 "type": "plain_text"
7 },
8 "type": "email_text_input"
9 },
10 "hint": {
11 "text": "Please enter your email",
12 "type": "plain_text"
13 },
14 "label": {
15 "text": "Email",
16 "type": "plain_text"
17 },
18 "type": "input_layout"
19}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "email_text_input".

1{
2 "type": "email_text_input",
3 "action_id": "<the action identifier of the email text input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<the value of the input>"
7}
Example payload
1{
2 "type": "email_text_input",
3 "action_id": "email",
4 "action_type": "remote",
5 "timestamp": "2023-07-12T08:17:43.887Z",
6 "value": "chuck@norris.com"
7}

Rich text input

A rich text input shows a rich text editor where the user can enter formatted text (Markdown). Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "rich_text_input".
Additional properties
  • initial_value (optional): The initial value in the input when it’s loaded.
Example

rich_text_input

The following video shows the rich text input in action.

1{
2 "element": {
3 "action_id": "notes",
4 "placeholder": {
5 "text": "Your notes go here",
6 "type": "plain_text"
7 },
8 "type": "rich_text_input"
9 },
10 "hint": {
11 "text": "Please enter your notes",
12 "type": "plain_text"
13 },
14 "label": {
15 "text": "Notes",
16 "type": "plain_text"
17 },
18 "optional": true,
19 "type": "input_layout"
20}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "rich_text_input".

1{
2 "type": "rich_text_input",
3 "action_id": "<the action identifier of the rich text input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<the value (raw Markdown) of the input>"
7}
Example payload
1{
2 "type": "rich_text_input",
3 "action_id": "notes",
4 "action_type": "remote",
5 "timestamp": "2023-07-19T10:54:20.331Z",
6 "value": "**Title**
7
8*Italic*
9
10~~Strikethrough~~
11
12`A piece of code`
13
14> A quote
15
16- Unordered 1
17- Unordered 2
18
191. Ordered 1
202. Ordered 2"
21}

There are 3 supported list input types:

  • String List Input
  • Number List Input
  • Email List Input

Properties

The list input component does not have any properties of its own. See specific variants below for their properties.

Inherited properties

Inherited from Snap:

  • type (required): Type of the list input component. Should be set according to the list input type, see below.
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

String list input

A string list input allows users to enter a list of text items. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "string_list".
Additional Properties
  • min_items (optional): The minimum number of items that can be added. Defaults to 1.
  • max_items (optional): The maximum number of items that can be added.
  • multiline (optional): Indicates whether the input should allow multiple lines of text. Defaults to false.
  • min_item_length (optional): The minimum text length of the inputs, can’t be greater than max_item_length.
  • max_item_length (optional): The maximum text length of the inputs, can’t be less than min_item_length.
  • initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.
Example

Standard string list input with a minimum of 1 item, maximum of 3 items, minimum item length set to 3 and maximum item length set to 15.

list_input_string

1{
2 "element": {
3 "action_id": "keywords",
4 "max_items": 3,
5 "min_items": 1,
6 "max_item_length": 15,
7 "min_item_length": 3,
8 "placeholder": {
9 "text": "Add keyword here",
10 "type": "plain_text"
11 },
12 "type": "string_list"
13 },
14 "hint": {
15 "text": "When a customer includes these keywords in a Slack message, they are prompted to send the message to your DevRev inbox.",
16 "type": "plain_text"
17 },
18 "label": {
19 "text": "List of strings",
20 "type": "plain_text"
21 },
22 "type": "input_layout"
23}

Multiline string list input with a minimum of 1 item and a maximum of 2 items.

list_input_string_multiline

1{
2 "element": {
3 "action_id": "multiline",
4 "max_items": 2,
5 "min_items": 1,
6 "multiline": true,
7 "placeholder": {
8 "text": "Add a keyword here",
9 "type": "plain_text"
10 },
11 "type": "string_list"
12 },
13 "hint": {
14 "text": "When a customer includes these multiline keywords in a Slack message, they are prompted to send the message to your DevRev inbox.",
15 "type": "plain_text"
16 },
17 "label": {
18 "text": "List of strings",
19 "type": "plain_text"
20 },
21 "type": "input_layout"
22}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "string_list".

1{
2 "type": "string_list",
3 "action_id": "<the action identifier of the string list input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of strings as inputted by the user>"]
7}
Example payload

Standard string list input.

1{
2 "type": "string_list",
3 "action_id": "keywords",
4 "action_type": "remote",
5 "timestamp": "2023-07-21T05:33:52.182Z",
6 "value": ["hello", "this is", "a test"]
7}

Multiline string list input.

1{
2 "type": "string_list",
3 "action_id": "multiline",
4 "action_type": "remote",
5 "timestamp": "2023-07-21T05:33:52.182Z",
6 "value": ["Hello this
7is a multiline string", "And here
8is another
9one"]
10}

Number List Input

A list of numbers input allows users to enter a list of numeric items. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "number_list".
Additional Properties
  • min_items (optional): The minimum number of items that can be added.
  • max_items (optional): The maximum number of items that can be added.
  • min_item_value (optional): The minimum value of the inputs, can’t be greater than max_item_value.
  • max_item_value (optional): The maximum value of the inputs, can’t be less than min_item_value.
  • initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.
Example

list_input_number

1{
2 "element": {
3 "action_id": "numbers",
4 "max_item_value": 90,
5 "min_item_value": 0,
6 "placeholder": {
7 "text": "Add warning value here (min 0, max 90)",
8 "type": "plain_text"
9 },
10 "type": "number_list"
11 },
12 "hint": {
13 "text": "Add warning values for code coverage reports",
14 "type": "plain_text"
15 },
16 "label": {
17 "text": "List of numbers",
18 "type": "plain_text"
19 },
20 "type": "input_layout"
21}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "number_list".

1{
2 "type": "number_list",
3 "action_id": "<the action identifier of the number list input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of numbers as strings as inputted by the user>"]
7}
Example Payload
1{
2 "type": "number_list",
3 "action_id": "numbers",
4 "action_type": "remote",
5 "timestamp": "2023-07-21T05:33:52.182Z",
6 "value": ["25", "42", "60"]
7}

Email List Input

A list of email input allows users to enter a list of emails. Works with Input Layout blocks.

Inherited properties

Inherited from Snap:

  • type (required): The type of the input component, should be set to "email_list".
Additional Properties
  • min_items (optional): The minimum number of items that can be added.
  • max_items (optional): The maximum number of items that can be added.
  • initial_values (optional): The initial values in the inputs when they are loaded. This is an array of strings. If min_items or max_items are set, the length of the array should be within the range.
Example

list_input_email

1{
2 "element": {
3 "action_id": "emails",
4 "placeholder": {
5 "text": "Enter email here",
6 "type": "plain_text"
7 },
8 "type": "email_list"
9 },
10 "hint": {
11 "text": "When these emails are included in a Slack message, they automatically receive an email notification.",
12 "type": "plain_text"
13 },
14 "label": {
15 "text": "List of emails",
16 "type": "plain_text"
17 },
18 "type": "input_layout"
19}
Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "email_list".

1{
2 "type": "email_list",
3 "action_id": "<the action identifier of the email list input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of emails as strings as inputted by the user>"]
7}
Example Payload
1{
2 "type": "email_list",
3 "action_id": "emails",
4 "action_type": "remote",
5 "timestamp": "2023-07-21T05:33:52.182Z",
6 "value": ["hello@hello.com", "example@example.com", "bonjour@hello.com"]
7}

A select menu that allows a user to choose one item from a list of options. Works with Input Layout and Actions blocks.

Properties

  • options (required): A list of options that appear in the menu, of type Plain Text Option.
  • initial_selected_option (optional): The initial option that’s selected when the element is loaded. A single option that exactly matches one of the options within options.
Inherited properties

Inherited from Snap:

  • type (required): Type of the static select component, should be set to "static_select".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

A static select snap with 4 options.

static_select

1{
2 "action_id": "static_select",
3 "action_type": "remote",
4 "initial_selected_option": {
5 "text": {
6 "text": "Forrest Gump",
7 "type": "plain_text"
8 },
9 "value": "forrest-gump"
10 },
11 "options": [
12 {
13 "text": {
14 "text": "Forrest Gump",
15 "type": "plain_text"
16 },
17 "value": "forrest-gump"
18 },
19 {
20 "text": {
21 "text": "The Shawshank Redemption",
22 "type": "plain_text"
23 },
24 "value": "the-shawshank-redemption"
25 },
26 {
27 "text": {
28 "text": "The Godfather",
29 "type": "plain_text"
30 },
31 "value": "the-godfather"
32 },
33 {
34 "text": {
35 "text": "The Dark Knight",
36 "type": "plain_text"
37 },
38 "value": "the-dark-knight"
39 }
40 ],
41 "type": "static_select"
42}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "static_select".

1{
2 "type": "static_select",
3 "action_id": "<the action identifier of the static select>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<selected Plain Text Option object>"
7}
Example Payload
1{
2 "action_id": "static_select",
3 "action_type": "remote",
4 "type": "static_select",
5 "value": {
6 "text": { "text": "The Godfather", "type": "plain_text" },
7 "value": "the-godfather"
8 },
9 "timestamp": "2023-07-12T08:21:06.027Z"
10}

A select menu that allows a user to choose multiple items from a list of options. Works with Input Layout and Actions blocks.

Properties

  • options (required): A list of options that appear in the menu, of type Plain Text Option.
  • initial_selected_options (optional): The initial options that are selected when the element is loaded. Each of them should exactly match one of the options within options.
  • max_selected_items (optional): The maximum number of items that can be selected.
Inherited properties

Inherited from Snap:

  • type (required): The type of the multi-static select component, should be set to "multi_static_select".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

A multi-static select snap with 4 options.

multi_static_select

1{
2 "action_id": "multi_static_select",
3 "action_type": "remote",
4 "initial_selected_options": [
5 {
6 "text": {
7 "text": "Forrest Gump",
8 "type": "plain_text"
9 },
10 "value": "forrest-gump"
11 }
12 ],
13 "options": [
14 {
15 "text": {
16 "text": "Forrest Gump",
17 "type": "plain_text"
18 },
19 "value": "forrest-gump"
20 },
21 {
22 "text": {
23 "text": "The Shawshank Redemption",
24 "type": "plain_text"
25 },
26 "value": "the-shawshank-redemption"
27 },
28 {
29 "text": {
30 "text": "The Godfather",
31 "type": "plain_text"
32 },
33 "value": "the-godfather"
34 },
35 {
36 "text": {
37 "text": "The Dark Knight",
38 "type": "plain_text"
39 },
40 "value": "the-dark-knight"
41 }
42 ],
43 "type": "multi_static_select"
44}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "multi_static_select".

1{
2 "type": "multi_static_select",
3 "action_id": "<the action identifier of the multi-static select>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<array of selected Plain Text Option objects>"]
7}
Example Payload
1{
2 "action_id": "multi_static_select",
3 "action_type": "remote",
4 "type": "multi_static_select",
5 "value": [
6 {
7 "text": { "text": "Forrest Gump", "type": "plain_text" },
8 "value": "forrest-gump"
9 },
10 {
11 "text": { "text": "The Dark Knight", "type": "plain_text" },
12 "value": "the-dark-knight"
13 }
14 ],
15 "timestamp": "2023-07-12T08:21:24.700Z"
16}

List of radio inputs that allow a user to choose one item from a list of options. Works with input layout and actions blocks.

Properties

  • options (required): A list of options that appear in a stack of radio inputs, of type plain text option.
  • initial_selected_option (optional): The initial option that’s selected when the element is loaded. A single option that exactly matches one of the options within options.
Inherited properties

Inherited from Snap:

  • type (required): Type of the radio button group component, should be set to "radio_buttons".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

A radio button snap with 3 options.

radio_buttons

1{
2 "action_id": "in-app",
3 "action_type": "remote",
4 "options": [
5 {
6 "text": {
7 "text": "Important updates only (Mentions & assignments)",
8 "type": "plain_text"
9 },
10 "value": "imp"
11 },
12 {
13 "text": {
14 "text": "All new updates",
15 "type": "plain_text"
16 },
17 "value": "all"
18 },
19 {
20 "text": {
21 "text": "Never",
22 "type": "plain_text"
23 },
24 "value": "none"
25 }
26 ],
27 "type": "radio_buttons"
28}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "radio_buttons".

1{
2 "type": "radio_buttons",
3 "action_id": "<the action identifier of the radio buttons>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<selected Plain Text Option object>"
7}
Example Payload
1{
2 "action_id": "in-app",
3 "action_type": "remote",
4 "type": "radio_buttons",
5 "value": {
6 "text": { "text": "All new updates", "type": "plain_text" },
7 "value": "all"
8 },
9 "timestamp": "2023-07-12T08:21:46.621Z"
10}

Toggles allow users to quickly switch between two possible states. Works with Input Layout and Actions blocks.

Properties

  • initial_value (optional): The initial value of the toggle (a boolean).
  • description (optional): A Plain Text element that defines the description shown below the toggle.
Inherited properties

Inherited from Snap:

  • type (required): The type of the toggle button component, should be set to "toggle".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

toggle

1{
2 "elements": [
3 {
4 "elements": [
5 {
6 "action_id": "toggle",
7 "description": {
8 "text": "This is a toggle",
9 "type": "plain_text"
10 },
11 "type": "toggle"
12 },
13 {
14 "action_id": "toggle_checked",
15 "description": {
16 "text": "This is a checked toggle",
17 "type": "plain_text"
18 },
19 "initial_value": true,
20 "type": "toggle"
21 },
22 {
23 "action_id": "toggle_disabled",
24 "description": {
25 "text": "This is a disabled toggle",
26 "type": "plain_text"
27 },
28 "disabled": true,
29 "type": "toggle"
30 }
31 ],
32 "type": "actions"
33 }
34 ],
35 "type": "card"
36}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "toggle".

1{
2 "type": "toggle",
3 "action_id": "<the action identifier of the toggle>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<boolean indicating the state of the toggle>"
7}
Example Payload
1{
2 "action_id": "toggle",
3 "action_type": "remote",
4 "type": "toggle",
5 "value": true,
6 "timestamp": "2023-07-12T08:22:10.723Z"
7}

A component that allows a user to upload a file. Works with Input Layout and Actions blocks.

Properties

  • upload_button (required): A button that can be clicked to upload files.
  • min_files (optional): The minimum number of files that can be uploaded.
  • max_files (optional): The maximum number of files that can be uploaded.
  • initial_artifacts_ids (optional): The initial artifacts that are selected when the element is loaded. A list of DONv2 IDs.
Inherited properties

Inherited from Snap:

  • type (required): Type of the upload input component, should be set to "upload".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

upload

1{
2 "elements": [
3 {
4 "elements": [
5 {
6 "action_id": "upload",
7 "action_type": "remote",
8 "max_files": 5,
9 "min_files": 1,
10 "type": "upload",
11 "upload_button": {
12 "action_id": "upload_btn",
13 "style": "primary",
14 "text": {
15 "text": "Upload",
16 "type": "plain_text"
17 },
18 "type": "button",
19 "value": "upload"
20 }
21 }
22 ],
23 "type": "actions"
24 }
25 ],
26 "type": "card"
27}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "upload".

1{
2 "type": "upload",
3 "action_id": "<the action identifier of the upload input>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of artifact IDs as strings>"]
7}
Example Payload
1{
2 "action_id": "upload",
3 "action_type": "remote",
4 "type": "upload",
5 "value": [
6 "don:core:dvrv-us-1:devo/H66a8LUt:artifact/5",
7 "don:core:dvrv-us-1:devo/H66a8LUt:artifact/6"
8 ],
9 "timestamp": "2023-07-12T08:25:47.451Z"
10}

Layout Elements

Used when you want the user to interact without filling out a form. Similar to the Form block but without a submit button. It contains an array of elements.

Properties

  • elements (required): An array of elements. See the list of allowed elements below.
  • disable_on_action (optional): A boolean indicating whether all elements in the actions block should be disabled when one of the elements is interacted with. When the action is completed, the elements are re-enabled. Defaults to false. A use case for enabling this is if you have multiple actions that shouldn’t be executed concurrently or are incompatible with each other. An example of this would be a snap-in for selecting a meal for a company event. When the user selects a meal, the other meal options should be disabled until the order is placed. After that, the Snap-kit can be updated with the information about the selection.
Inherited properties

Inherited from Snap:

  • type (required): The type of the actions component, should be set to "actions".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Layout:

  • direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
  • alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
  • justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

Example

actions

1{
2 "elements": [
3 {
4 "action_id": "actions",
5 "action_type": "remote",
6 "options": [
7 {
8 "text": {
9 "text": "Checkbox 1",
10 "type": "plain_text"
11 },
12 "value": "checkbox_1"
13 },
14 {
15 "text": {
16 "text": "Checkbox 2",
17 "type": "plain_text"
18 },
19 "value": "checkbox_2"
20 }
21 ],
22 "type": "checkboxes"
23 },
24 {
25 "action_id": "submit",
26 "action_type": "remote",
27 "style": "primary",
28 "text": {
29 "text": "Button",
30 "type": "plain_text"
31 },
32 "type": "button",
33 "value": "submit"
34 }
35 ],
36 "type": "actions"
37}

The following video shows the behavior of the Actions block with disable_on_action set to true.

1{
2 "elements": [
3 {
4 "elements": [
5 {
6 "text": "This is an example of an Actions Snap with disable_on_action set to true. When you click one of the buttons, the other buttons are disabled until the action finishes.",
7 "type": "plain_text"
8 }
9 ],
10 "type": "content"
11 },
12 {
13 "direction": "row",
14 "disable_on_action": true,
15 "elements": [
16 {
17 "action_id": "button_1",
18 "action_type": "remote",
19 "style": "primary",
20 "text": {
21 "text": "Button 1",
22 "type": "plain_text"
23 },
24 "type": "button",
25 "value": "button_1"
26 },
27 {
28 "action_id": "button_2",
29 "action_type": "remote",
30 "style": "secondary",
31 "text": {
32 "text": "Button 2",
33 "type": "plain_text"
34 },
35 "type": "button",
36 "value": "button_2"
37 },
38 {
39 "action_id": "button_3",
40 "action_type": "remote",
41 "style": "destructive",
42 "text": {
43 "text": "Button 3",
44 "type": "plain_text"
45 },
46 "type": "button",
47 "value": "button_3"
48 }
49 ],
50 "type": "actions"
51 }
52 ],
53 "type": "card"
54}

A card is a container for various types of content. It contains an array of elements.

Properties

  • elements (required): An array of elements. See the list of allowed elements below.
  • title (optional): The title of the card.
  • is_collapsible (optional): Whether the card is collapsible or not. Defaults to false.
  • default_collapsed (optional): Whether the card is collapsed by default or not. Defaults to false.
Inherited properties

Inherited from Snap:

  • type (required): The type of the card component, should be set to "card".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Layout:

  • direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
  • alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
  • justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

Example

Default and collapsible card example.

card

1[
2 {
3 "elements": [
4 {
5 "elements": [
6 {
7 "text": "Hello this is an example of a card that can have different types of elements inside it",
8 "type": "plain_text"
9 }
10 ],
11 "type": "content"
12 }
13 ],
14 "type": "card"
15 },
16 {
17 "default_collapsed": true,
18 "elements": [
19 {
20 "elements": [
21 {
22 "text": "Hello this is an example of a collapsible card",
23 "type": "plain_text"
24 }
25 ],
26 "type": "content"
27 }
28 ],
29 "is_collapsible": true,
30 "title": {
31 "text": "Collapsible Card Example",
32 "type": "plain_text"
33 },
34 "type": "card"
35 }
36]

A content block is used to hold various types of content. It contains an array of elements.

Properties

  • elements (required): An array of elements. See the list of allowed elements below.
Inherited properties

Inherited from Snap:

  • type (required): The type of the content component, should be set to "content".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Layout:

  • direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
  • alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
  • justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

Example

content

1{
2 "elements": [
3 {
4 "text": "Hello this is an example of content",
5 "type": "plain_text"
6 },
7 {
8 "alt_text": "My heart goes",
9 "image_url": "https://media1.giphy.com/media/5kq0GCjHA8Rwc/giphy.gif?cid=ecf05e47uvd6y50d5jrxs2odyj0y90oq2v6hd6xz6j578183&rid=giphy.gif&ct=g",
10 "type": "image"
11 }
12 ],
13 "type": "content"
14}

A form block that collects information from users.

Properties

  • elements (required): An array of elements. See the list of allowed elements below.
  • submit_action (required): A button that can be clicked to submit the form.
Inherited properties

Inherited from Snap:

  • type (required): The type of the form component, should be set to "form".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Layout:

  • direction (optional): The direction of the layout. Similar to flex-direction. Possible values: "row", "column".
  • alignment (optional): The alignment of the layout. Similar to align-items. Possible values: "start", "center", "end", "baseline", "stretch".
  • justify (optional): The justification of the layout. Similar to justify-content. Possible values: "start", "center", "end", "between", "around", "evenly".

Allowed elements

The elements array can contain the following Snaps:

Example

A form composed of plain text inputs, number inputs, checkboxes, radio buttons, static select, and multi-static select snaps.

form

1{
2 "action_id": "user_form",
3 "elements": [
4 {
5 "element": {
6 "action_id": "name",
7 "action_type": "remote",
8 "min_length": 10,
9 "placeholder": {
10 "text": "Enter your name",
11 "type": "plain_text"
12 },
13 "type": "plain_text_input"
14 },
15 "hint": {
16 "text": "Please enter your name",
17 "type": "plain_text"
18 },
19 "label": {
20 "text": "User Name",
21 "type": "plain_text"
22 },
23 "optional": true,
24 "type": "input_layout"
25 },
26 {
27 "element": {
28 "action_id": "age",
29 "max_value": 120,
30 "min_value": 10,
31 "type": "number_input"
32 },
33 "label": {
34 "text": "Age",
35 "type": "plain_text"
36 },
37 "type": "input_layout"
38 },
39 {
40 "element": {
41 "action_id": "checkboxes",
42 "options": [
43 {
44 "description": {
45 "text": "Description for option 1",
46 "type": "plain_text"
47 },
48 "text": {
49 "text": "Option 1",
50 "type": "plain_text"
51 },
52 "value": "option_1"
53 },
54 {
55 "description": {
56 "text": "Description for option 1",
57 "type": "plain_text"
58 },
59 "text": {
60 "text": "Option 2",
61 "type": "plain_text"
62 },
63 "value": "option_2"
64 }
65 ],
66 "type": "checkboxes"
67 },
68 "type": "input_layout"
69 },
70 {
71 "element": {
72 "action_id": "radio_buttons",
73 "options": [
74 {
75 "description": {
76 "text": "Description for option 1",
77 "type": "plain_text"
78 },
79 "text": {
80 "text": "Radio Option 1",
81 "type": "plain_text"
82 },
83 "value": "radio_option_1"
84 },
85 {
86 "description": {
87 "text": "Description for option 1",
88 "type": "plain_text"
89 },
90 "text": {
91 "text": "RadioOption 2",
92 "type": "plain_text"
93 },
94 "value": "radio_option_2"
95 }
96 ],
97 "type": "radio_buttons"
98 },
99 "type": "input_layout"
100 },
101 {
102 "element": {
103 "action_id": "multi_static_select",
104 "options": [
105 {
106 "text": {
107 "text": "Select option 1",
108 "type": "plain_text"
109 },
110 "value": "select-option-1"
111 },
112 {
113 "text": {
114 "text": "Select option 2",
115 "type": "plain_text"
116 },
117 "value": "select-option-2"
118 }
119 ],
120 "type": "multi_static_select"
121 },
122 "label": {
123 "text": "Multi Select",
124 "type": "plain_text"
125 },
126 "type": "input_layout"
127 },
128 {
129 "element": {
130 "action_id": "single_static_select",
131 "initial_selected_option": {
132 "text": {
133 "text": "Single 1",
134 "type": "plain_text"
135 },
136 "value": "single-option-1"
137 },
138 "options": [
139 {
140 "text": {
141 "text": "Single 1",
142 "type": "plain_text"
143 },
144 "value": "single-option-1"
145 },
146 {
147 "text": {
148 "text": "Single 2",
149 "type": "plain_text"
150 },
151 "value": "single-option-2"
152 }
153 ],
154 "placeholder": {
155 "text": "Placeholder here",
156 "type": "plain_text"
157 },
158 "type": "static_select"
159 },
160 "label": {
161 "text": "Single Select",
162 "type": "plain_text"
163 },
164 "type": "input_layout"
165 }
166 ],
167 "submit_action": {
168 "action_id": "submit",
169 "style": "primary",
170 "text": {
171 "text": "Submit",
172 "type": "plain_text"
173 },
174 "type": "button",
175 "value": "submit"
176 },
177 "type": "form"
178}

Action payload

Inherits type, action_id, action_type and timestamp from Base Payload, type is set to "form".

1{
2 "type": "form",
3 "action_id": "<the action identifier of the form>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": "<an object containing action payloads of nested Snaps>"
7}
Example payload
1{
2 "action_id": "user_form",
3 "action_type": "remote",
4 "type": "form",
5 "value": {
6 "name": {
7 "action_id": "name",
8 "type": "plain_text_input",
9 "value": "Chuck Norris"
10 },
11 "age": { "action_id": "age", "type": "number_input", "value": "83" },
12 "checkboxes": {
13 "action_id": "checkboxes",
14 "type": "checkboxes",
15 "value": [
16 {
17 "description": {
18 "text": "Description for option 1",
19 "type": "plain_text"
20 },
21 "text": { "text": "Option 1", "type": "plain_text" },
22 "value": "option_1"
23 },
24 {
25 "description": {
26 "text": "Description for option 1",
27 "type": "plain_text"
28 },
29 "text": { "text": "Option 2", "type": "plain_text" },
30 "value": "option_2"
31 }
32 ]
33 },
34 "radio_buttons": {
35 "action_id": "radio_buttons",
36 "type": "radio_buttons",
37 "value": {
38 "description": {
39 "text": "Description for option 1",
40 "type": "plain_text"
41 },
42 "text": { "text": "RadioOption 2", "type": "plain_text" },
43 "value": "radio_option_2"
44 }
45 },
46 "multi_static_select": {
47 "action_id": "multi_static_select",
48 "type": "multi_static_select",
49 "value": [
50 {
51 "text": { "text": "Select option 1", "type": "plain_text" },
52 "value": "select-option-1"
53 },
54 {
55 "text": { "text": "Select option 2", "type": "plain_text" },
56 "value": "select-option-2"
57 }
58 ]
59 },
60 "single_static_select": {
61 "action_id": "single_static_select",
62 "type": "static_select",
63 "value": {
64 "text": { "text": "Single 1", "type": "plain_text" },
65 "value": "single-option-1"
66 }
67 }
68 },
69 "timestamp": "2023-07-12T08:26:10.842Z"
70}

A layout that holds the elements that the user can interact with in a form. Works with Form blocks.

Properties

  • element (required): The input element. See the list of allowed elements below.
  • label (optional): A Plain Text element that defines the label shown above the input element.
  • hint (optional): A Plain Text element that defines the hint shown below the label.
  • optional (optional): A boolean that indicates whether the input element may be empty when a user submits the modal. For toggle, if this value is false, then it needs to be always toggled (needs to be true). Defaults to false.
  • disabled (optional): Disables the input and prevents changes to the value.
  • disabled_text (optional): The text that’s shown on hover if the component is disabled.
Inherited properties

Inherited from Snap:

  • type (required): Type of the input layout component, should be set to "input_layout".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Hideable:

  • hidden (optional): Indicates whether the element is hidden. You can use this to pass values to the backend without showing them to the user.

Allowed element types

Example

input_layout

1{
2 "action_id": "user_form",
3 "alignment": "end",
4 "direction": "row",
5 "elements": [
6 {
7 "element": {
8 "action_id": "name",
9 "min_length": 10,
10 "placeholder": {
11 "text": "Enter your name",
12 "type": "plain_text"
13 },
14 "type": "plain_text_input"
15 },
16 "label": {
17 "text": "User Name",
18 "type": "plain_text"
19 },
20 "optional": true,
21 "type": "input_layout"
22 },
23 {
24 "element": {
25 "action_id": "age",
26 "max_value": 120,
27 "min_value": 10,
28 "type": "number_input"
29 },
30 "label": {
31 "text": "Age",
32 "type": "plain_text"
33 },
34 "type": "input_layout"
35 },
36 {
37 "element": {
38 "action_id": "hidden_field",
39 "initial_value": "something you do not wish to expose to the user",
40 "type": "plain_text_input"
41 },
42 "hidden": true,
43 "type": "input_layout"
44 },
45 ],
46 "justify": "between",
47 "submit_action": {
48 "action_id": "submit",
49 "style": "primary",
50 "text": {
51 "text": "Submit",
52 "type": "plain_text"
53 },
54 "type": "button",
55 "value": "submit"
56 },
57 "type": "form"
58}

Data pickers

A component that provides a list of parts that allows a user to choose multiple parts from a list. Works with Input Layout and Actions blocks.

Properties

  • initial_parts_selected_options (optional): The initially selected parts, a list of DONv2 IDs.
  • max_selected_items (optional): The maximum number of parts that can be selected.
  • allowed_part_types (optional): A list of part types that are selectable from the list of parts in the dropdown. Possible values: "capability", "component", "custom_part", "enhancement", "feature", "linkable", "microservice", "product", "runnable".
Inherited properties

Inherited from Snap:

  • type (required): Type of the part picker component, should be set to "part_picker".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

Part picker snap with 2 selected parts.

part_picker

1{
2 "element": {
3 "action_id": "part_picker",
4 "action_type": "remote",
5 "max_selected_items": 5,
6 "type": "part_picker"
7 },
8 "label": {
9 "text": "Part",
10 "type": "plain_text"
11 },
12 "type": "input_layout"
13}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "part_picker".

1{
2 "type": "part_picker",
3 "action_id": "<the action identifier of the part picker>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of part DONv2 IDs as strings>"]
7}
Example payload
1{
2 "action_id": "part_picker",
3 "action_type": "remote",
4 "type": "part_picker",
5 "value": [
6 "don:core:dvrv-us-1:devo/H66a8LUt:feature/1",
7 "don:core:dvrv-us-1:devo/H66a8LUt:feature/2"
8 ],
9 "timestamp": "2023-07-12T08:29:01.788Z"
10}

A component that provides a list of tags that allow a user to choose multiple tags from a list. Works with Input Layout and Actions blocks.

Properties

  • initial_tags_selected_options (optional): The initially selected tags, a list of DONv2 IDs.
  • max_selected_items (optional): The maximum number of tags that can be selected.
Inherited properties

Inherited from Snap:

  • type (required): Type of the tag picker component, should be set to "tag_picker".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

Tag picker snap with 1 selected tag.

tag_picker

1{
2 "element": {
3 "action_id": "tag_picker",
4 "action_type": "remote",
5 "max_selected_items": 5,
6 "type": "tag_picker"
7 },
8 "label": {
9 "text": "Tag",
10 "type": "plain_text"
11 },
12 "type": "input_layout"
13}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "tag_picker".

1{
2 "type": "tag_picker",
3 "action_id": "<the action identifier of the tag picker>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of tag DONv2 IDs as strings>"]
7}
Example payload
1{
2 "action_id": "tag_picker",
3 "action_type": "remote",
4 "type": "tag_picker",
5 "value": ["don:core:dvrv-us-1:devo/H66a8LUt:tag/7"],
6 "timestamp": "2023-07-12T08:32:15.001Z"
7}

A component that provides a list of users that allow a user to choose multiple users from a list. Works with Input Layout and Actions blocks.

Properties

  • user_types (optional): The types of users that are allowed to be selected. Defaults to ["rev_user", "dev_user"]. Possible values: "rev_user", "dev_user", "sys_user".
  • initial_rev_users_selected_options (optional): The initially selected customers, a list of DONv2 IDs.
  • initial_dev_users_selected_options (optional): The initially selected dev users, a list of DONv2 IDs.
  • initial_sys_users_selected_options (optional): The initially selected sys users, a list of DONv2 IDs.
  • max_selected_items (optional): The maximum number of users that can be selected.
Inherited properties

Inherited from Snap:

  • type (required): Type of the user picker component, should be set to "user_picker".
  • block_id (optional): A unique identifier for the snap. If not provided, a random ID is generated.

Inherited from Action:

  • action_id (required): An identifier for the action. Should be unique in the snap.
  • action_type (optional): Indicates whether the action is handled by the backend or client. This is mandatory to pass if you have an action to be performed. Possible values: "remote", "client".

Inherited from Focusable:

  • focus_on_load (optional): Indicates whether the component should be focused on load or not. Only 1 item can have the property set to true in the snap. Defaults to false.

Inherited from Placeholder:

  • placeholder (optional): A Plain Text element that defines the placeholder text shown on the element.

Inherited from Disabled:

  • disabled (optional): Indicates whether the element is disabled.

Example

User picker snap with 1 selected user.

user_picker

1{
2 "element": {
3 "action_id": "user_picker",
4 "action_type": "remote",
5 "max_selected_items": 5,
6 "type": "user_picker"
7 },
8 "label": {
9 "text": "User",
10 "type": "plain_text"
11 },
12 "type": "input_layout"
13}

Action payload

Inherits type, action_id, action_type, and timestamp from Base Payload, type is set to "user_picker".

1{
2 "type": "user_picker",
3 "action_id": "<the action identifier of the user picker>",
4 "action_type": "<the type of the action as defined in the Snap>",
5 "timestamp": "<timestamp as a string in ISO 8601 format>",
6 "value": ["<an array of user DONv2 IDs as strings>"]
7}
Example Payload
1{
2 "action_id": "user_picker",
3 "action_type": "remote",
4 "type": "user_picker",
5 "value": ["don:identity:dvrv-us-1:devo/H66a8LUt:devu/5"],
6 "timestamp": "2023-07-12T08:32:15.001Z"
7}

Example snap-kit

In this updated JSON, the divider component is added to create a visual separation. The checkboxes component allows for selecting multiple options. The part_picker component allows for selecting parts, and the tag_picker component allows for selecting tags. You can customize the options, initial selections, and other values according to your requirements.

1{
2 "object": "source_id",
3 "body": "Giphy",
4 "type": "timeline_comment",
5 "snap_kit_body": {
6 "snap_in_id": "snap_in_id",
7 "snap_in_action_name": "giphy",
8 "body": {
9 "snaps": [
10 {
11 "type": "card",
12 "title": {
13 "text": "Hip hip hurray!",
14 "type": "plain_text"
15 },
16 "elements": [
17 {
18 "type": "content",
19 "elements": [
20 {
21 "type": "image",
22 "image_url": "https://example.com/image.jpg",
23 "alt_text": "Awesome GIF"
24 }
25 ]
26 },
27 {
28 "type": "divider"
29 },
30 {
31 "type": "checkboxes",
32 "options": [
33 {
34 "text": {
35 "text": "Option 1",
36 "type": "plain_text"
37 },
38 "value": "option1"
39 },
40 {
41 "text": {
42 "text": "Option 2",
43 "type": "plain_text"
44 },
45 "value": "option2"
46 }
47 ]
48 },
49 {
50 "type": "part_picker",
51 "initial_parts_selected_options": ["part1"],
52 "max_selected_items": 2
53 },
54 {
55 "type": "tag_picker",
56 "initial_tags_selected_options": ["tag1"],
57 "max_selected_items": 3
58 },
59 {
60 "type": "actions",
61 "direction": "row",
62 "justify": "center",
63 "elements": [
64 {
65 "type": "button",
66 "action_id": "send",
67 "action_type": "remote",
68 "style": "primary",
69 "text": {
70 "text": "Send",
71 "type": "plain_text"
72 },
73 "value": "send"
74 },
75 {
76 "type": "button",
77 "action_id": "shuffle",
78 "action_type": "remote",
79 "style": "primary",
80 "text": {
81 "text": "Shuffle",
82 "type": "plain_text"
83 },
84 "value": "shuffle"
85 },
86 {
87 "type": "button",
88 "action_id": "cancel",
89 "action_type": "remote",
90 "style": "danger",
91 "text": {
92 "text": "Cancel",
93 "type": "plain_text"
94 },
95 "value": "cancel"
96 }
97 ]
98 }
99 ]
100 }
101 ]
102 }
103 }
104}
Built with