Skip to main content

Multiselect

This page explains how to use a Multiselect widget to allow users to select multiple options from a given list.

Using Multiselect

Display static options

To display static options in a Multiselect widget, you can use the Options property.

The options must be specified as an array of objects, where each object has two properties: label and value. The label property represents the text that's displayed to the user, while the value property is the actual data that's stored and used in your application. For example:

[
{
"label": "Blue",
"value": "BLUE"
},
{
"label": "Green",
"value": "GREEN"
},
{
"label": "Red",
"value": "RED"
}
]

Set default values

The Default Selected Values property in a widget allows you to specify an initial value for the widget when it's first displayed. This is useful for pre-populating the widget or ensuring that specific options are selected by default. To use this property, set its value to the value of the desired option from the Options property.

For example, if you want the default selected values to be RED and GREEN, you can set the Default Selected Values property to:

[
"GREEN",
"RED"
]

Display options dynamically

You can dynamically generate options by fetching data from queries or JS functions by binding the response to the Options property.


Example 1: suppose you want to use a Multiselect widget to allow users to select one or more countries from a database, with the dynamic population of options.

  1. Fetch data from the sample database users using a SELECT query fetchData to retrieve distinct country values as label and value:
SELECT DISTINCT country as label, country as value FROM users;
  1. In the Multiselect Options property, display the data using:
{{fetchData.data}}

With this configuration, the Multiselect widget displays a list of unique country values directly from the query. It is recommended to retrieve the data in a structured format directly from the query, as it simplifies the configuration when displaying the options in the Multiselect widget.


Example 2: if the data retrieved from the query is not in the desired format, you can use JavaScript to transform it before passing it to the Multiselect widget.

  1. Use the users table in the sample database and fetch the unique country values using the following getdata SQL query:
SELECT DISTINCT country FROM users;

This query retrieves unique country values from the users table. The retrieved data is in the form of an array of objects, where each object has a country key.

  1. Use JavaScript to transform the data by adding it to the Options property.
{{getdata.data.map( p => ({label: p.country, value: p.country}))}}

The code transforms each item in the getdata array by using the map() function to create a new object with a label and value property, both set to the country value of each object in the array.

Access selected options

If you want to retrieve the selected values from a Multiselect widget and bind them to other widgets or JavaScript functions, you can use the following properties:

  • selectedOptionValues: This property returns the value of the selected options in the Multiselect widget.

  • selectedOptionLabels: This property returns the label of the selected options in the Multiselect widget.

Both properties, selectedOptionValues and selectedOptionLabels, update automatically when the user selects or deselects a new option in the Multiselect widget.


Example: suppose you want to filter the table data based on the user-selected countries from a Multiselect widget.

  1. Create a new query called filterdata and add a SQL statement to select all the data from the users table where the country column matches the selected options from a Multiselect widget.
SELECT *
FROM users
WHERE country IN ({{"'" + MultiSelect.selectedOptionLabels.join("', '") + "'"}})
LIMIT 10;
info

When using dynamic binding with queries that contain SQL keywords such as SELECT, WHERE, AND, and other keywords, a prepared statement cannot be used. Therefore, it is recommended to turn off the prepared statement in the filterdata query for the Multiselect widget.

  1. Display the data by binding the query response to the Table Data property of the Table widget tblUserData, as shown below:
{{filterdata.data}}
  1. Set the onOptionChange event of the Multiselect widget to run the filterdata query. This updates the displayed data in real-time as the user selects or deselects options.
Display images on table row selection
Access selected options

Properties

Properties allow you to edit the widget, connect it with other widgets and customize the user actions.

Widget properties

These properties allow you to edit the widget. All of these properties are present in the property pane of the widget.

PropertyData typeDescription
OptionsArraySets the labels and values for different items/options in the list of the Multiselect widget. Options must be specified as an array of objects with a label and value property.
Default ValueArraySets a default option that is captured as user input unless it is changed by the user. Multiple values can be provided as CSV or an array of strings for a Multiselect dropdown.
PlaceholderStringSets the Placeholder of the Multiselect widget.
RequiredBooleanWhen turned on, it makes a user input required and disables any form submission until input is made.
VisibleBooleanControl widget's visibility on the page. When turned off, the widget isn't visible when the app is published
DisabledBooleanDisables input/selection to the widget. The widget is visible to the user but user input/selection is not allowed.
TooltipStringIt sets a tooltip for the widget. You can add hints or extra information about the required input from the user.
Animate LoadingBooleanAllows you to control a widget’s animation on the page load.
Server Side FilteringBooleanEnables server-side filtering via an API / Query request. Use this property when your Select option data is being bound to an API / Query.
Allow Select AllBooleanControls the visibility of select all option in the dropdown.
HeightStringIt configures how a widget’s height reacts to content changes. It has three possible configurations:
Fixed: The height of the widget remains as set using drag and resize.
Auto Height: The height of the widget reacts to content changes.
Auto Height with limits: Same as Auto height, with a configurable option to set the minimum and maximum number of rows that can be occupied by the widget.
TextStringSets the Placeholder of the Multiselect widget.
PositionStringSets the label position of the widget.
AlignmentStringSets the label alignment of the widget.
Allow SearchingBooleanMakes the dropdown list filterable.
WidthNumberSets the label width of the widget as the number of columns.

Reference properties

These properties can be referenced in other widgets, queries, or JS functions using the dot operator. For instance, you can use MultiSelect1.isVisible to get the visibility status.

Reference PropertyData typeDescription
filterTextStringThe filter text for Server side filtering
isVisibleBooleanThis property indicates whether the widget is visible or not.
isDisabledBooleanThis property indicates whether the widget is disabled or not.
optionsArrayThis property shows the values of all the options.
selectedOptionLabelsArrayAn array of Labels of the options are displayed in a Multiselect dropdown. This label changes if the default values of the dropdown change or the user changes an option selection
selectedOptionValuesArrayAn array of values of the options are displayed in a Multiselect dropdown. This value changes if the default values of the dropdown change or the user changes an option selection
isDirtyBooleanIndicates whether the Multiselect widget has been used by the end user during their session.
isValidBooleanThis property indicates whether the widget is valid or not.

Style properties

Style properties allow you to change the look and feel of the widget. All of these properties are present in the property pane of the widget.

PropertyData typeDescription
Font ColorStringAllows you to set text color for the label.
Font SizeStringAllows you to set the size of the label.
EmphasisStringAllows you to choose a font style (bold or italic).
Border RadiusStringAllows you to define curved corners.
Box ShadowStringAllows you to choose from the available shadow styles.

Events

When the event is triggered, these event handlers can run queries, JS code, or other supported actions

EventsDescription
onOptionChangeSets the action to be run when the user selects/unselects an option.
onDropdownOpenSets the action to be run when the user opens the dropdown.
onDropdownCloseSets the action to be run when the user opens the dropdown.
onFilterUpdateTriggers an action on change of filterText