App Canvas Block Reference | Benchling Documentation

ButtonUiBlock

A ButtonUiBlock creates a button that users can interact with. The text value sets the button text, and the type field currently only supports the BUTTON value. Button blocks can trigger user interaction webhooks.

Example JSON

{
    "id": "submit1",
    "type": "BUTTON",
    "text": "Submit"
}

An App Canvas showing a single Submit button — A button block rendered in an App Canvas

ChipUiBlock

A ChipUiBlock creates a “chip” that represents a Benchling entity. “Chips” are dynamic elements that can be clicked to take a user to the entity. The value field contains the Benchling API ID of the entity; the chip will appear in the canvas with the entity’s label.

Example JSON

{
    "id": "chip1",
    "type": "CHIP",
    "value": "seq_ay0tljLF"
}

An App Canvas showing an entity chip labeled with the entity's name — A chip block rendered in an App Canvas

DropdownUiBlock

A DropdownUiBlock creates a selectable dropdown menu from an existing Benchling dropdown (created from the Registry Settings page). The dropdownId field is the Benchling API ID of the dropdown, and value is the Benchling API ID of the desired dropdown option. The value may be null.

Example JSON

{
    "id": "dropdown1",
    "type": "DROPDOWN",
    "value": "sfso_bal3XKdt",
    "dropdownId": "sfs_wZIWqdMB",
    "enabled": true
}

An App Canvas showing a dropdown menu with a selected option — A dropdown block rendered in an App Canvas

DropdownMultiValueUiBlock

A DropdownMultiValueUiBlock is a DropdownUiBlock that allows users to select multiple values instead of a single value. It is a distinct block type, so type must be DROPDOWN_MULTIVALUE rather than DROPDOWN. The value field is an array of strings (instead of a single string), and contains some number of Benchling API IDs of the desired dropdown options. The value field may be empty.

Example JSON

{
    "id": "dropdown1",
    "type": "DROPDOWN_MULTIVALUE",
    "value": ["sfso_bal3XKdt","sfso_8hn3UIsr"],
    "dropdownId": "sfs_wZIWqdMB",
    "enabled": true
}

FileUploadUiBlock

A FileUploadUiBlock lets users upload files (up to 10 per block) of the file format(s) specified. A Benchling App can then retrieve the uploaded files via the /blobs endpoint.

An animation of a user attaching a file to an App Canvas file upload block — A file upload block rendered in an App Canvas

{
  "enabled": true,
  "id": "user_defined_id",
  "label": "Attach your file",
  "required": true,
  "value": [
    "c33fe52d-fe6a-4c98-adcd-211bdf6778f7"
  ],
  "fileTypes": [
    ".pdf", ".csv"
  ],
  "maxFiles": 10,
  "type": "FILE_UPLOAD"
}

The fileTypes field can be used to restrict the accepted files to the specified formats.

maxFiles lets the app restrict the number of files that can be submitted per FileUploadUiBlock.

The value field may be empty. When provided, the Canvas loads with the specified blob provided in the FileUploadUiBlock.

MarkdownUiBlock

A MarkdownUiBlock creates a section where the value field is rendered as markdown. Basic options like bold, italics, and links are supported.

Example JSON

{
    "id": "md1",
    "type": "MARKDOWN",
    "value": "### This is a markdown text section\n---\nBasic markdown options like **bold**, _italics_, and [links]() are supported"
}

An App Canvas showing a markdown section with a heading, a horizontal rule, and inline bold and italic text — A markdown block rendered in an App Canvas

SearchInputUiBlock

A SearchInputUiBlock creates an input that allows users to search for Benchling entities. value should be null for new blocks, and will contain the API ID of user-selected result. itemType must be one of dna_sequence, dna_oligo, aa_sequence, custom_entity, mixture, box, container, location, or plate. schemaId is required; can be the API ID of a specific schema to limit results, or null otherwise.

Example JSON

{
    "id": "input_block_1",
    "type": "SEARCH_INPUT",
    "itemType": "dna_sequence",
    "schemaId": null,
    "value": null,
    "enabled": true
}

An App Canvas showing a search input with entity results in a dropdown list — A search input block rendered in an App Canvas

SearchInputMultiValueUiBlock

A SearchInputMultiValueUiBlock is a SearchInputUiBlock that allows users to input multiple search values instead of a single value. It is a distinct block type, so type must be SEARCH_INPUT_MULTIVALUE rather than SEARCH_INPUT. value will be an empty array for new blocks, and will contain some number of user-selected API IDs when filled.

Example JSON

{
    "id": "input_block_1",
    "type": "SEARCH_INPUT_MULTIVALUE",
    "itemType": "dna_sequence",
    "schemaId": null,
    "value": ["seq_W5FWe9U8","seq_HD8k9MAn"],
    "enabled": true
}

SectionUiBlock

A SectionUiBlock acts as a container to group other blocks. Elements in the same section will appear inline (i.e. side-by-side), while elements in separate sections (or otherwise independent) will appear as discrete blocks (i.e. one on top of the other).

Example JSON

Two independent blocks, which render stacked:

{
    "id": "label1",
    "type": "MARKDOWN",
    "value": "**This is an input label**"
},
{
    "id": "input_block_2",
    "type": "TEXT_INPUT",
    "placeholder": "Placeholder",
    "value": null,
    "enabled": true
}

An App Canvas showing a label above a text input, stacked vertically — Two independent blocks rendered one on top of the other

The same two blocks as children of a section, which render inline:

{
   "children": [
     {
       "id": "label1",
       "type": "MARKDOWN",
       "value": "**This is an input label**"
     },
     {
       "id": "input_block_2",
       "type": "TEXT_INPUT",
       "placeholder": "Placeholder",
       "value": null,
       "enabled": true,
       "canvasEnabled": true
     }
   ],
   "id": "section1",
   "type": "SECTION"
}

An App Canvas showing a label and a text input side-by-side within one section — The same blocks grouped in a section, rendered side-by-side

SelectorInputUiBlock

A SelectorInputUiBlock creates a selectable dropdown menu with dropdown options defined by the app. options is the enum of all valid values, and value should be one of the valid options (or null).

Example JSON

{
    "id": "selectorinput_1",
    "type": "SELECTOR_INPUT",
    "options": ["Red", "Blue", "Green"],
    "value": "Blue",
    "enabled": true
}

An App Canvas showing a selector input with app-defined options in a dropdown list — A selector input block rendered in an App Canvas

SelectorInputMultiValueUiBlock

A SelectorInputMultiValueUiBlock is a SelectorInputUiBlock that allows users to select multiple values instead of a single value. It is a distinct block type, so type must be SELECTOR_INPUT_MULTIVALUE rather than SELECTOR_INPUT. value will be some number of the valid options, or an empty array.

Example JSON

{
    "id": "selectorinput_1",
    "type": "SELECTOR_INPUT_MULTIVALUE",
    "options": ["Red", "Blue", "Green"],
    "value": ["Blue","Red"],
    "enabled": true
}

TableUiBlock

A TableUiBlock renders a structured table based on a Benchling data frame. The source field accepts a type and dataFrameId: The only currently supported value for type is DATA_FRAME, and the value of dataFrameId must be the API ID of an existing data frame. Data frames are created separately (see the Data Frames API documentation for more detail).

Data frame IDs are prefixed dset_, so a valid dataFrameId looks like a dataset ID. A DATASET source type with a datasetId field also exists, but it is deprecated, and writes to it are converted to a data frame source, so use DATA_FRAME and dataFrameId.

Canvas tables currently support text-type columns only.

Example JSON

{
  "id": "table_1",
  "name": "Second Table",
  "source": {
    "dataFrameId": "dset_mfz1f3ai2e8y",
    "type": "DATA_FRAME"
  },
  "type": "TABLE"
}

An App Canvas showing a table of data frame rows and columns — A table block rendered in an App Canvas

TextInputUiBlock

A TextInputUiBlock creates a plain-text input that users can fill. placeholder sets placeholder text; value should be set to null for new blocks, and will contain user-provided string.

Example JSON

{
    "id": "input_block_2",
    "type": "TEXT_INPUT",
    "placeholder": "Placeholder",
    "value": null,
    "enabled": true
}