Dropdown

The Dropdown component can be used to collect user input from a list of options. This document goes through all the properties related to the Dropdown component.

info

To get the configuration of legacy Dropdown component, please refer to this document.

Data

Property	Description	Expected Value
Label	Text to display as the label for the field.	String (e.g., `Country`).
Placeholder	A hint displayed to guide the user on what to enter.	String (e.g., `Choose an option`).

Options

Allows you to add options to the dropdown field. You can click on Add new option and add options manually or enable Dynamic options and enter the options using code.

Example Code for Dynamic Columns

Passing an array of objects and specifying each value:

{{
    [
      {
        label: "option1",
        value: 1,
        caption: "First option",
        disable: false,
        visible: true,
        default: true,
      },
      { label: "option2", value: 2, caption: null, disable: false, visible: true },
      { label: "option3", value: 3, caption: null, disable: false, visible: true },
    ];
}}

caption is optional. When set, it displays additional descriptive text beneath the option label in the dropdown list. It does not appear in the selected value shown after an option is chosen. Default is null.

Passing an array of objects with a default value from a Table component's selected row:

{
  {
    queries.getEmployees.data.map((option) => ({
      label: option.firstname,
      value: option.firstname,
      disable: false,
      visible: true,
      default: option.firstname === components.table1.selectedRow.firstname,
    }));
  }
}

Example Schema for Group Options

Enter the schema in the following syntax to use the Group Options

{{[
  {
    label: 'Fruits',
    options: [
      { value: 'apple', label: 'Apple', disable:true },
      { value: 'orange', label: 'Orange' },
      { value: 'banana', label: 'Banana' },
    ],
  },
  {
    label: 'Vegetables',
    options: [
      { value: 'carrot', label: 'Carrot' },
      { value: 'broccoli', label: 'Broccoli' },
      { value: 'spinach', label: 'Spinach' },
    ],
  },
  {
    label: 'Dairy',
    options: [
      { value: 'milk', label: 'Milk' },
      { value: 'cheese', label: 'Cheese' },
      { value: 'butter', label: 'Butter' },
    ],
  },
]}}

Options Loading State

Allows you to add a loading state to the dynamically generated options. You can enable or disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.

Sort Options

Sort all the options in the selected pattern. Choose from None, a-z or z-a.

Search

Turn on Show search in options to add a search box to the options menu, then use Search type to choose where the filtering happens.

Client Side Search

This is the default search option. The component filters the options it already holds, in the browser, and highlights the matching text in option labels and captions. The complete option list has to be loaded into the component for this to work.

Server Side Search

Use Server side search when the option list is too large to load into the browser. The component stops filtering locally, and you bind its options to a query that returns only the matching rows.

warning

Server side mode does not fetch anything on its own, it only stops the component from filtering. If you enable it without binding the options to a query, the menu shows the full unfiltered list while the user types.

To set up server side search:

Turn on Show search in options, then set Search type to Server side.

Create a query that filters on the component's searchText:

SELECT name AS label, id AS value
FROM public.sample_data_orders
WHERE name ILIKE '%{{components.dropdown1.searchText || ""}}%'
LIMIT 50

Replace dropdown1 with the name of your component.

Bind Option values and Option labels, or the Schema if you are using dynamic options, to the query's data. For example, {{queries.searchOrders.data.map(o => o.value)}}.
Add an event handler to the component:
Event: On search text changed
Action: Run Query
Query: the query you created in step 2
Optionally, click on fx next to Loading state and enter {{queries.searchOrders.isLoading}} so that the menu shows a spinner while the query runs.

info

On search text changed fires on every keystroke, so each keystroke runs the query. Keep a LIMIT in the query to bound the number of rows returned.

Sort Options still applies in Server side mode and re-sorts whatever the query returned, in the browser. Set it to None if your query already sorts the results.

Events

Event	Description
On select	Triggers whenever an option is selected.
On search text changed	Triggers whenever the search text is changed.
On focus	Triggers whenever the user clicks inside the input field.
On blur	Triggers whenever the user clicks outside the input field.

info

Check Action Reference docs to get detailed information about all the Actions.

Component specific actions (CSA)

The following actions of the component can be controlled using the component-specific actions (CSA), you can trigger it using an event or use a RunJS query.

Actions	Description	How To Access
clear( )	Clears the selected option.	`components.dropdown1.clear()`
setVisibility( )	Sets the visibility of the component.	`components.dropdown1.setVisibility(false)`
setLoading( )	Sets the loading state of the component.	`components.dropdown1.setLoading(true)`
setDisable( )	Disables the component.	`components.dropdown1.setDisable(true)`
selectOption( )	Selects an option.	`components.dropdown1.selectOption(2)`

Note: The data type passed to CSAs like selectOption() depends on how you configure the component. When adding options manually using the Add new option button, values must be strings (for example, components.dropdown1.selectOption(['2'])). When using dynamic options, supply values with the correct data types as they appear in your code logic.

For example, if the code is:

{
  {
    [
      {
        label: "option1",
        value: 1,
        disable: false,
        visible: true,
        default: true,
      },
      { label: "option2", value: 2, disable: false, visible: true },
      { label: "option3", value: 3, disable: false, visible: true },
    ];
  }
}

You should pass numeric values in the selectOption component-specific action since the value type is Number:

components.dropdown1.selectOption(2);

Exposed Variables

Variable	Description	How To Access
searchText	This variable is initially empty and holds the value whenever the user searches on the dropdown.	`{{components.dropdown1.searchText}}`
label	Holds the label name of the dropdown.	`{{components.dropdown1.label}}`
value	Holds the value selected by the user in the component.	`{{components.dropdown1.value}}`
selectedOption	Holds the label, value, and caption of the selected option.	`{{components.dropdown1.selectedOption.label}}`, `{{components.dropdown1.selectedOption.caption}}`
isValid	Indicates if the input meets validation criteria.	`{{components.dropdown1.isValid}}`
options	Holds all the option values of the dropdown. Each entry includes `label`, `value`, and `caption`.	`{{components.dropdown1.options}}`
isVisible	Indicates if the component is visible.	`{{components.dropdown1.isVisible}}`
isLoading	Indicates if the component is loading.	`{{components.dropdown1.isLoading}}`
isDisabled	Indicates if the component is disabled.	`{{components.dropdown1.isDisabled}}`
isMandatory	Indicates if the field is required.	`{{components.dropdown1.isMandatory}}`

Validation

Validation Option	Description	Expected Value
Make this field mandatory	Displays a 'Field cannot be empty' message if no option is selected.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Custom validation	Specifies a validation error message for specific conditions.	Logical Expression (e.g., `{{components.dropdown.value<5&&"Value needs to be more than 5"}}`).

Additional Actions

Action	Description	Configuration Options
Show clear selection button	Gives a button to clear all selections.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Show search in options	Enables a search option.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Search type	Sets whether the options menu is filtered in the browser (Client side) or by a query (Server side). Only visible when Show search in options is enabled.	Select Client side or Server side, or click on fx and enter an expression that resolves to a boolean (`{{true}}` for Server side).
Loading state	Enables a loading spinner, often used with `isLoading` to indicate progress. Toggle or set dynamically.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Visibility	Controls component visibility. Toggle or set dynamically.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Disable	Enables or disables the component. Toggle or set dynamically.	Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Tooltip	Provides additional information on hover. Supports Plain text, Markdown, and HTML formats.	String (e.g., `Enter your name here.` ).

Devices

Property	Description	Expected Value
Show on desktop	Makes the component visible in desktop view.	You can set it with the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.
Show on mobile	Makes the component visible in mobile view.	You can set it with the toggle button or dynamically configure the value by clicking on fx and entering a logical expression.

Styles

Label

Label Property	Description	Configuration Options
Color	Sets the color of the component's label.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Alignment	Sets the position of the label and input field.	Click on the toggle options or click on fx to input code that programmatically returns an alignment value - side or top.
Width	Sets the width of the input field.	Enable Auto width to use the standard width automatically. Disable it to manually adjust the width using the slider or by entering a numeric value via fx. You can also choose whether the width is calculated relative to the Container or relative to the Field.

Field

Field Property	Description	Configuration Options
Background	Sets the background color of the component.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Border	Sets the border color of the component.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Text	Sets the text color of the text entered in the component.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Placeholder text	Sets the color of the placeholder text displayed when no option is selected.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Accent	Sets the color of the border when the dropdown is opened.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Error text	Sets the text color of validation message that displays.	Select the color or click on fx and input code that programmatically returns a Hex color code.
Icon	Allows you to select an icon for the component.	Enable the icon visibility, select icon and icon color
Border radius	Modifies the border radius of the component.	Enter a number or click on fx and enter a code that programmatically returns a numeric value.
Box shadow	Sets the box shadow properties of the component.	Select the box shadow color and adjust the related properties.

Container

Padding
Allows you to maintain a standard padding by enabling the Default option.

Advanced

Property	Description	Configuration Options
CSS class	Adds a custom CSS class to the component, which can be targeted using Custom Styles for advanced styling.	Enter one or more class names.

info

The Advanced section is available only if your plan has the Custom Styles feature enabled.

Data​

Options​

Example Code for Dynamic Columns​

Example Schema for Group Options​

Options Loading State​

Sort Options​

Search​

Client Side Search​

Server Side Search​

Events​

Component specific actions (CSA)​

Exposed Variables​

Validation​

Additional Actions​

Devices​

Styles​

Label​

Field​

Container​

Advanced​

Data

Options

Example Code for Dynamic Columns

Example Schema for Group Options

Options Loading State

Sort Options

Search

Client Side Search

Server Side Search

Events

Component specific actions (CSA)

Exposed Variables

Validation

Additional Actions

Devices

Styles

Label

Field

Container

Advanced