Skip to main content

Tree Select (ALPHA)

Alpha feature: invite only

Responsive Widgets are in alpha and available by invitation only on Business and Enterprise plans. Behavior and properties may change. To request access, open a support ticket and name the feature Responsive Widgets (ALPHA).

The Tree Select widget shows a dropdown with nested options, such as categories and sub-categories. In Single mode, users pick one option. In Multi mode, users check several options. Use it when your options form a hierarchy, for example departments and teams.

Tree Select widget in a Responsive app
Tree Select widget

Widget type: WDS_TREE_SELECT_WIDGET

Content properties​

These properties appear in the Content tab of the property pane.

Data​

Selection type string​

Sets how many options users can pick. You cannot bind this property. Options:

  • Single: users pick one option.
  • Multi: the dropdown shows checkboxes so users can pick several options.

Default: Single.

Options array<object>​

Sets the nested options. Each option is an object with a label, a value, and an optional children array of more options. You can bind data from a query or API with {{ }}.

To keep the app fast, the widget shows at most 5000 options in total and at most 10 levels of nesting. It drops options past these limits.

Default value:

[
{
"label": "Blue",
"value": "BLUE",
"children": [
{ "label": "Dark Blue", "value": "DARK_BLUE" },
{ "label": "Light Blue", "value": "LIGHT_BLUE" }
]
},
{ "label": "Green", "value": "GREEN" },
{ "label": "Red", "value": "RED" }
]

Default selected value string​

Sets the option that is selected when the widget loads. Enter the option's value. Default: BLUE. Shows only when Selection type is Single.

Default selected values array​

Sets the options that are checked when the widget loads. Enter an array of option values. Default: ["GREEN"]. Shows only when Selection type is Multi.

Example:

["GREEN", "LIGHT_BLUE"]

Label​

Text string​

Sets the label text shown above the dropdown. Default: Label.

Validations​

Required boolean​

Makes a selection mandatory. When on and nothing is selected, the widget is invalid and shows the message "Please select an option" after the user interacts with it. Default: off.

General​

Tooltip string​

Shows help text or details next to the label.

Display selected string​

Sets which checked options the widget reports and shows. You cannot bind this property. Options:

  • Show only parent items
  • Show only child items
  • Show all items

Default: Show all items. Shows only when Selection type is Multi.

Placeholder string​

Sets the text shown when nothing is selected. Default: Select an option.

Visible boolean​

Controls whether the widget is visible when the app runs. Default: on.

Disabled boolean​

Stops users from changing the selection. Default: off.

Animate loading boolean​

Shows a loading animation while the widget's data loads. Default: on.

Allow clearing value boolean​

Shows an icon that clears the current selection. Default: off.

Expand all by default boolean​

Expands all nested options when the dropdown opens. Default: off.

Style properties​

These properties appear in the Style tab of the property pane.

Custom styling​

These settings are in the Custom styling section, at the end of the Style tab. An empty setting uses the theme value. For theme colors, dark mode, and the rules for custom CSS, see Custom styling.

Accent color string​

Builds the hover, pressed, focus, and text colors of this widget from one color, in light and dark mode. Lists and menus that the widget opens use them too. Empty means the accent of the nearest container that sets one, or the theme accent.

Background string​

Sets the background of the input field box. Takes a theme color or a custom color.

Text color string​

Sets the text color of the input field box. Takes a theme color or a custom color. When it is empty and Background is set, the widget picks a readable text color.

Border color string​

Sets the border color of the input field box. Takes a theme color or a custom color. A color with no Border width draws a thin border.

Border width string​

Sets the border width of the input field box. Options: From theme (default), None, Thin, Medium, Thick. You cannot bind this property.

Corners string​

Sets the corner radius of the input field box. Options: From theme (default), Sharp, Rounded, Pill. You cannot bind this property.

Custom CSS string​

Adds plain CSS to this widget. Rules apply only inside the widget, and & is the box around the widget, its label included, not the part inside it. To style an inner part, use its element selector, for example button or input. You cannot bind this property.

Reference properties​

Reference properties let you read the widget's state in bindings and code, for example {{TreeSelect1.isVisible}}. You cannot set them directly.

isVisible boolean​

Shows whether the widget is visible.

Example:

{{TreeSelect1.isVisible}}

selectedOptionValue string​

Holds the value of the selected option in Single mode. It is empty if the value is not in Options. It is undefined in Multi mode.

Example:

{{TreeSelect1.selectedOptionValue}}

selectedOptionLabel string​

Holds the label of the selected option in Single mode. It is undefined in Multi mode.

Example:

{{TreeSelect1.selectedOptionLabel}}

selectedOptionValues array<string>​

Holds the values of the checked options in Multi mode. Values that are not in Options are left out. It is undefined in Single mode.

Example:

{{TreeSelect1.selectedOptionValues}}

selectedOptionLabels array<string>​

Holds the labels of the checked options in Multi mode. It is undefined in Single mode.

Example:

{{TreeSelect1.selectedOptionLabels}}

isDisabled boolean​

Shows whether the widget is disabled.

Example:

{{TreeSelect1.isDisabled}}

isValid boolean​

Shows whether the widget is valid. It is false only when Required is on and nothing is selected.

Example:

{{TreeSelect1.isValid}}

isDirty boolean​

Shows whether the user has changed the selection. It resets to false when the default value for the current mode changes.

Example:

{{TreeSelect1.isDirty}}

options array<object>​

Holds the nested options set in Options.

Example:

{{TreeSelect1.options}}

Methods​

Methods let you change the widget's properties from code, for example in a JS Object.

setVisibility (param: boolean): Promise​

Shows or hides the widget.

Example:

TreeSelect1.setVisibility(true)

setDisabled (param: boolean): Promise​

Turns the disabled state on or off.

Example:

TreeSelect1.setDisabled(false)

setRequired (param: boolean): Promise​

Turns the Required setting on or off.

Example:

TreeSelect1.setRequired(true)

setSelectedOption (param: string): Promise​

Sets the selected option by its value. Use it in Single mode.

Example:

TreeSelect1.setSelectedOption("DARK_BLUE")

setSelectedOptions (param: array): Promise​

Sets the checked options by their values. Use it in Multi mode.

Example:

TreeSelect1.setSelectedOptions(["GREEN", "RED"])

Events​

onSelectionChange​

Runs when the user changes the selection.

onDropdownOpen​

Runs when the dropdown opens.

onDropdownClose​

Runs when the dropdown closes.