ComboBox (ALPHA)

BusinessEnterprise

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 ComboBox widget is a dropdown with a text input. Users type to filter the list, then pick one option. Use it for long lists, for example a list of countries or customers. You can filter the list in the browser, or turn on server side filtering to run a query as the user types.

ComboBox widget

Widget type: WDS_COMBOBOX_WIDGET

Content properties

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

Data

Data type string

Sets the kind of dropdown. Options:

• Select: users pick from the list only. Choosing this option changes the widget into a Select widget.
• ComboBox: users can also type to filter the list.

Source Data array<object>

Takes an array of objects. Each object becomes one option. You can bind data from a query or API with {{ }}.

Default value:

[
  { "name": "Blue", "code": "BLUE" },
  { "name": "Green", "code": "GREEN" },
  { "name": "Red", "code": "RED" }
]

Example:

{{getCountries.data}}

Label key string

Sets the field in Source Data that each option shows as its label. Pick a key from the list, or switch to JS to write an expression. The value must be a string or an array of strings, and it cannot be empty. Default: name.

Value key string

Sets the field in Source Data that each option uses as its value. Pick a key from the list, or switch to JS to write an expression. The key must exist in Source Data, and the values must be unique. Default: code.

Default selected value string

Sets the option that is selected when the widget loads. Enter a value, or an object with label and value keys. The value must be present in Source Data for the option to show as selected. Default: empty.

Example:

GREEN

Label

Text string

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

Search & filters

Server side filtering boolean

Turns on server side filtering. When on, the widget does not filter the options itself. Instead, it updates filterText as the user types and runs onFilterUpdate. Your query then returns the matching options. Default: off.

onFilterUpdate

Runs when the filter text changes. The widget waits until the user stops typing for 800 ms before it updates filterText. Shows only when Server side filtering is on.

Example: bind Source Data to {{searchCustomers.data}}, set this event to run searchCustomers, and use {{ComboBox1.filterText}} in the query's filter.

Validations

Required boolean

Makes a selection mandatory. When on and no option 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.

Placeholder string

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

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.

Reference properties

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

isVisible boolean

Shows whether the widget is visible.

Example:

{{ComboBox1.isVisible}}

selectedOptionValue string

Holds the value of the selected option. It is empty when no option is selected.

Example:

{{ComboBox1.selectedOptionValue}}

selectedOptionLabel string

Holds the label of the selected option.

Example:

{{ComboBox1.selectedOptionLabel}}

isDisabled boolean

Shows whether the widget is disabled.

Example:

{{ComboBox1.isDisabled}}

isValid boolean

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

Example:

{{ComboBox1.isValid}}

isDirty boolean

Shows whether the user has changed the selection. It resets to false when Default selected value changes.

Example:

{{ComboBox1.isDirty}}

options array<object>

Holds the list of options as { label, value } objects, built from Source Data, Label key, and Value key.

Example:

{{ComboBox1.options}}

filterText string

Holds the text the user typed into the input. Use it for server side filtering. Default: empty.

Example:

{{ComboBox1.filterText}}

serverSideFiltering boolean

Shows whether Server side filtering is on.

Example:

{{ComboBox1.serverSideFiltering}}

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:

ComboBox1.setVisibility(true)

setDisabled (param: boolean): Promise

Turns the disabled state on or off.

Example:

ComboBox1.setDisabled(false)

setRequired (param: boolean): Promise

Turns the Required setting on or off.

Example:

ComboBox1.setRequired(true)

setOptions (param: array): Promise

Sets the list of options.

Example:

ComboBox1.setOptions([{ label: "Blue", value: "BLUE" }, { label: "Red", value: "RED" }])

setSelectedOption (param: string): Promise

Sets the selected option by its value.

Example:

ComboBox1.setSelectedOption("RED")

Events

onSelectionChange

Runs when the user selects a different option.

onFilterUpdate

Runs when the filter text changes and Server side filtering is on. You set it in the Search & filters section.

onDropdownOpen

Runs when the dropdown opens.

onDropdownClose

Runs when the dropdown closes.