Checkbox Tree component for Retool Apps

A group of checkboxes to toggle boolean values in a multi-level tree.

Version: Self-hosted 3.114 Stable

Checkbox Tree is a preset version of Checkbox Group. It has been preconfigured with common options for a nested tree layout.

Retool recently released this improved version of the Checkbox Tree component, and use of the legacy component is discouraged.

Demo

Properties

All properties for this object with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read property values.

captionByIndex

A list of captions for each item, by index.

Type	array
Format	Plain Text
Array values	string
Mutability	Read-only
Default	[]

Examples

["Caption 1", "Caption 2"]

---

checkedPathArray

The selected items, in nested order.

Type	array
Array values	number
Mutability	Read-only

---

checkedPathStrings

The selected items, in strong format.

Type	array
Array values	string
Mutability	Read-only

---

checkStrictly

Whether to check the treeNode. Parent treeNode and children treeNodes are not included.

Type	boolean
Mutability	Control Usage Retool UI Inspector

---

delimiter

The delimiter used in checkedPathStrings.

Type	string
Mutability	Control Usage Retool UI Inspector

---

deprecatedLabels

A list of labels for each item. Falls back to the corresponding value if no label is provided.

Type	array
Array values	string
Mutability	Read-only
Default	[]

Examples

["Label 1", "Label 2", "Label 3"]

---

disabled

Whether input, interaction, selection, or triggering is disabled.

Type	boolean
Format	True/False
Mutability	Control Usage Retool UI Inspector > Interaction Method setDisabled()
Default	false

Examples

true

---

disabledByIndex

A list of values for each item, by index, that reflect whether they are disabled.

Type	array
Array values	boolean
Mutability	Read-only
Default	[]

Examples

[true, false, true]

---

disabledValues

A list of values not available for selection.

Type	array
Array values	boolean
Mutability	Read-only

---

groupLayout

The layout of grouped items.

Type	string
Mutability	Control Usage Retool UI Inspector > Appearance
Allowed Values	Value UI Option Description multiColumn Tree Display items in multiple columns based on the number of items and size. singleColumn Single column Always display items in a single column. wrap Wrap Wrap items. tree
Default	auto

---

heightType

Whether the height automatically adjusts to fit content or is a fixed size.

Type	string
Format	Plain Text
Mutability	Control Usage Retool UI Inspector > Spacing
Allowed Values	Value Description auto Expand to fit content. fixed Fixed height. fill
Default	fixed

---

hiddenByIndex

A list of items, by index, and whether they are hidden.

Type	array
Array values	boolean
Mutability	Read-only
Default	[]

Examples

[true, false, true]

---

labelPosition

The position of the label relative to the input field or value.

Type	string
Format	Plain Text
Mutability	Control Usage Retool UI Inspector > Content > Add-ons > Label
Allowed Values	Value UI Option Description top Top Above the input field or value. left Left Left of the input field or value.
Default	left

Examples

top

---

labels

A list of labels for each item. Falls back to the corresponding value if no label is provided.

Type	array
Array values	string
Mutability	Read-only
Default	[]

Examples

["Label 1", "Label 2", "Label 3"]

---

leafPathArray

A list of expanded keys`.

Type	array
Array values	string
Mutability	Read-only

---

leafPathStrings

A list of expanded keys in hyphen-separated format`.

Type	array
Array values	string
Mutability	Read-only

---

maxCount

The maximum number of items to allow.

Type	number
Mutability	Control Usage Retool UI Inspector

---

minColumnWidth

The minimum width of a column when using a multi-column layout.

Type	number
Format	number
Mutability	Control Usage Retool UI Inspector > Appearance
Default	null

Examples

100

---

minCount

The minimum number of items to allow.

Type	number
Mutability	Control Usage Retool UI Inspector

---

parentKeysByIndex

A list of parent keys, by index.

Type	array
Array values	string
Mutability	Read-only

---

required

Whether a value is required to be selected.

Type	boolean
Format	True/False
Mutability	Control Usage Retool UI Inspector > Interaction > Validation rules
Default	false

Examples

true

---

selectedIndexes

A list of selected values, by index.

Type	array
Array values	number
Mutability	Read-only

---

selectedItems

A list of selected items.

Type	array
Mutability	Read-only
Default	[]

Examples

[{"id": "1", "name": "Item 1"}, {"id": "2", "name": "Item 2"}]

---

selectedLabels

A list of labels for selected values, by index.

Type	array
Array values	string
Mutability	Read-only

---

style

Custom style options.

Type	object
Mutability	Control Usage Retool UI Inspector > Appearance

---

tooltipByIndex

A list of tooltips for each item, by index.

Type	array
Array values	string
Mutability	Read-only
Default	[]

Examples

["Tooltip 1", "Tooltip 2"]

---

tooltipText

The tooltip text to display next to the label on hover.

Type	string
Format	Markdown
Mutability	Control Usage Retool UI Inspector > Content > Add-ons
Default	null

Examples

Submit

---

value

The value.

Type	array
Mutability	Read-only

---

values

A list of possible values from which to select.

Type	array
Mutability	Read-only

---

Methods

JavaScript API methods for this object. You can write JavaScript almost anywhere in Retool and use methods to manipulate data and property values.

checkboxTree.blur()

Remove focus from the input field.

Definition

checkboxTree.blur()

Examples

Remove focus from checkboxTree.

checkboxTree.blur();

---

checkboxTree.clearValidation()

Clear the validation message from the input field.

Definition

checkboxTree.clearValidation()

Examples

Clear the validation message from checkboxTree.

checkboxTree.clearValidation();

---

checkboxTree.clearValue()

Clear the current values.

Definition

checkboxTree.clearValue()

Examples

Clear the current value of checkboxTree.

checkboxTree.clearValue();

---

checkboxTree.focus()

Set focus on the input field.

Definition

checkboxTree.focus()

Examples

Set focus on checkboxTree.

checkboxTree.focus();

---

checkboxTree.resetValue()

Reset the current value to the default value.

Definition

checkboxTree.resetValue()

Examples

Reset the current value of checkboxTree.

checkboxTree.resetValue();

---

checkboxTree.scrollIntoView()

Scrolls the canvas or parent container so that the selected component appears in the visible area.

Definition

checkboxTree.scrollIntoView(options)

Parameters

options Required

object

The scroll options.

Object Properties

behavior Required

string

The scroll behavior.

Supported Values

auto	Scroll immediately to the specified position.
smooth	Scroll gradually to the specified position.

block Required

string

The scroll position relative to the component.

Supported Values

nearest	Scrolls only the minimum amount required for the component to appear in the visible area. Scrolling does not occur if the component is already in view.
start	Scrolls to position the component at the top of the visible area.
center	Scrolls to position the component in the middle of the visible area.
end	Scrolls to position the component at the bottom of the visible area.

Examples

Scroll the minimum amount to immediately bring checkboxTree into view.

checkboxTree.scrollIntoView({behavior: 'auto', block: 'nearest'});

---

checkboxTree.setDisabled()

Set the disabled value to toggle whether the input field is disabled. Defaults to true without a parameter.

Definition

checkboxTree.setDisabled(disabled)

Parameters

disabled

boolean

Whether input, interaction, selection, or triggering is disabled.

Examples

Disable checkboxTree.

checkboxTree.setDisabled(true);

Enable checkboxTree.

checkboxTree.setDisabled(false);

---

checkboxTree.setHidden()

Set the hidden value to toggle whether the component is visible. Defaults to true without a parameter.

Definition

checkboxTree.setHidden(hidden)

Parameters

hidden

boolean

Whether this object is hidden from view.

Examples

Hide checkboxTree.

checkboxTree.setHidden(true);

Unhide checkboxTree.

checkboxTree.setHidden(false);

---

checkboxTree.setValue()

Set the current value.

Definition

checkboxTree.setValue(value)

Parameters

value

string | number | boolean | object | array

The value.

Examples

Set the current value of checkboxTree to userValue.

checkboxTree.setValue(userValue);

---

Events

Events triggered by user interactions. Use event handlers to trigger queries or other actions in response to events.

change

The value is changed.

---