> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# App Canvas Block Reference

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

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

![An App Canvas showing a single Submit button](/_fern-files/_img/f74270f038346a615da4b5f6db44caaff4fc068dbcf43b92d7c15eada4095a70.webp)

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

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

![An App Canvas showing an entity chip labeled with the entity's name](/_fern-files/_img/8b0b0552d1badd3e321abeaa006b6fce5683bbdcc9bdcbb110303fe8231083a4.webp)

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

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

![An App Canvas showing a dropdown menu with a selected option](/_fern-files/_img/b0254ae1ec5baa023328c1a463720da3268e72ab6950c7e76ec8a918ced6e278.webp)

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

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

![An App Canvas showing a dropdown menu with a selected option](/_fern-files/_img/b0254ae1ec5baa023328c1a463720da3268e72ab6950c7e76ec8a918ced6e278.webp)

## 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](/_fern-files/benchling-040512.docs.buildwithfern.com/1fd1202a0fcaf6dc036326340a0a5ea58ace9ca11b72eff7a18215ad28216da2/assets/images/canvas-block-file-upload.gif)

```json
{
  "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**

```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](/_fern-files/_img/4ce46fa7f7c0396e4332804a4fbbd3cc4ed5402e4a702f84a3c8ab609601e52d.webp)

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

```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](/_fern-files/_img/34f669512dd9f3e2b453906ee9c8833045a6934b5ec1d4c79858a0edef652ef5.webp)

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

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

![An App Canvas showing a search input with entity results in a dropdown list](/_fern-files/_img/34f669512dd9f3e2b453906ee9c8833045a6934b5ec1d4c79858a0edef652ef5.webp)

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

```json
{
    "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](/_fern-files/_img/a3090789a4817fbc3f5f64798482a5bf12cf2966147799cc3400d32b214fdf2d.webp)

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

```json
{
   "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](/_fern-files/_img/8db1f50cb3ff00cc5c111f884a5daa2c389706f25c0e9012a69dde35753c5865.webp)

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

```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](/_fern-files/_img/3144a9fc504038e626afb64f23fe1c960ac4905a8074a92a261428a5934ae37f.webp)

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

```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](/docs/api/v2-beta/benchling-api-beta/data-frames) for more detail).

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

```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](/_fern-files/_img/ac0706bb3544062075a84e13faaf76bcadfcf7b054acb447e83793e4324af40b.webp)

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

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

![An App Canvas showing a plain-text input with placeholder text](/_fern-files/_img/d2f6e722ce5f25ea4c25b7795b97f9873c5ed2470335fd3302909ff626225fae.webp)