Skip to main content

Select (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 Select widget shows a dropdown list. Users pick one option from it. Use it when users must choose one value from a fixed list, for example a status or a country. If users need to type to find an option, use the ComboBox widget.

Select widget in a Responsive app
Select widget

Widget type: WDS_SELECT_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.
  • ComboBox: users can also type to filter the list. Choosing this option changes the widget into a ComboBox widget.

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.

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 {{Select1.isVisible}}. You cannot set them directly.

isVisible boolean​

Shows whether the widget is visible.

Example:

{{Select1.isVisible}}

selectedOptionValue string​

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

Example:

{{Select1.selectedOptionValue}}

selectedOptionLabel string​

Holds the label of the selected option.

Example:

{{Select1.selectedOptionLabel}}

isDisabled boolean​

Shows whether the widget is disabled.

Example:

{{Select1.isDisabled}}

isValid boolean​

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

Example:

{{Select1.isValid}}

isDirty boolean​

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

Example:

{{Select1.isDirty}}

options array<object>​

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

Example:

{{Select1.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:

Select1.setVisibility(true)

setDisabled (param: boolean): Promise​

Turns the disabled state on or off.

Example:

Select1.setDisabled(false)

setRequired (param: boolean): Promise​

Turns the Required setting on or off.

Example:

Select1.setRequired(true)

setOptions (param: array): Promise​

Sets the list of options.

Example:

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

setSelectedOption (param: string): Promise​

Sets the selected option by its value.

Example:

Select1.setSelectedOption("RED")

Events​

onSelectionChange​

Runs when the user selects a different option.

onDropdownOpen​

Runs when the dropdown opens.

onDropdownClose​

Runs when the dropdown closes.