MultiSelect (ALPHA)
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 MultiSelect widget shows a dropdown list where users can pick one or more options. The dropdown has a search input to filter the list. Use it when users may choose several values, for example tags or team members.

Widget type: WDS_MULTI_SELECT_WIDGET
Content properties
These properties appear in the Content tab of the property pane.
Data
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:
{{getTags.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 values array
Sets the options that are selected when the widget loads. Enter an array of values, a comma-separated string, or an array of objects with label and value keys. The values must be present in Source Data for the options to show as selected. Default: empty.
Example:
["BLUE", "RED"]
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. The search text also stays when the dropdown closes and opens again. Default: off.
onFilterUpdate
Runs when the filter text changes. The widget waits until the user stops typing for 1000 ms before it updates filterText. Shows only when Server side filtering is on.
Example: bind Source Data to {{searchTags.data}}, set this event to run searchTags, and use {{MultiSelect1.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.
Allow select all boolean
Shows a "select all" option in the dropdown. 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 {{MultiSelect1.isVisible}}. You cannot set them directly.
isVisible boolean
Shows whether the widget is visible.
Example:
{{MultiSelect1.isVisible}}
selectedOptionValues array
Holds the values of the selected options.
Example:
{{MultiSelect1.selectedOptionValues}}
selectedOptionLabels array
Holds the labels of the selected options.
Example:
{{MultiSelect1.selectedOptionLabels}}
isDisabled boolean
Shows whether the widget is disabled.
Example:
{{MultiSelect1.isDisabled}}
isValid boolean
Shows whether the widget is valid. It is false only when Required is on and no option is selected.
Example:
{{MultiSelect1.isValid}}
isDirty boolean
Shows whether the user has changed the selection. It resets to false when Default selected values changes.
Example:
{{MultiSelect1.isDirty}}
options array<object>
Holds the list of options as { label, value } objects, built from Source Data, Label key, and Value key.
Example:
{{MultiSelect1.options}}
filterText string
Holds the text the user typed into the dropdown's search input. Use it for server side filtering. Default: empty.
Example:
{{MultiSelect1.filterText}}
serverSideFiltering boolean
Shows whether Server side filtering is on.
Example:
{{MultiSelect1.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:
MultiSelect1.setVisibility(true)
setDisabled (param: boolean): Promise
Turns the disabled state on or off.
Example:
MultiSelect1.setDisabled(false)
setRequired (param: boolean): Promise
Turns the Required setting on or off.
Example:
MultiSelect1.setRequired(true)
setOptions (param: array): Promise
Sets the list of options.
Example:
MultiSelect1.setOptions([{ label: "Blue", value: "BLUE" }, { label: "Red", value: "RED" }])
setSelectedOption (param: array): Promise
Sets the selected options by their values.
Example:
MultiSelect1.setSelectedOption(["BLUE", "RED"])
Events
onSelectionChange
Runs when the user changes the selected options.
onFilterUpdate
Runs when the search 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.