Skip to main content

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 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.

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 and dark mode, 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.

This widget has no Custom CSS setting. It renders hidden helper elements next to the field, so custom CSS cannot be scoped to the widget alone.

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.