Skip to main content


Capture user input from a list of choices.

Dropdown components are useful for capturing user input for a single choice or multiple choices of various options.

Manually set dropdown options

Start by dragging a Dropdown component from the Components panel.

The default data that populates the dropdown is an array of objects, where each object contains a label and value key. The label is the text shown in the dropdown option, whereas the value is the output resulting from selecting that item in the dropdown. This value can be fed into other components and APIs via {{<DROPDOWN_NAME>.selectedOptionValue}} for a single choice or {{<DROPDOWN_NAME>.selectedOptionValues}} for multiple choices. (see section for Trigger an API on select).

Dropdown component populated with an object containing label and value

Alternatively, you can configure Options as a simple array of strings if the value and label for each option are expected to be the same.

Dropdown component populated with only an array of options

Customize dropdown label and default text

Edit the dropdown Label and Default selected value string(s), or Placeholder text if no default value is selected.

Update the dropdown properties

Toggle interaction and display settings

To allow users to select more than one option in the dropdown, toggle the Enable Multi-select switch. If selecting an option in the dropdown is necessary before proceeding to subsequent steps, enforce user input via Required. Additionally, the dropdown can be disabled by either setting user interaction as Disabled or toggling the Visible option to hide the component.

Enable multi-select to allow users to select more than one option

Note, to set multiple default selected values for a multi-select dropdown, add an array of the value strings inside bindings. For example, {{["TORONTO", "NEW YORK"]}}.

Default selected value string(s) takes an array to have multiple options selected by default

Dynamically set dropdown options from API response

Create an API called getOrders that queries the [Demo] Orders Postgres Database.

API with a SQL query to get orders

Reference the API response in the dropdown component Options via {{getOrders.response}}. Superblocks automatically configures the Value Field with one of the table columns from the resulting SQL response. Here we've configured the order id field to allow users to select specific orders from the dropdown and perform additional processing or investigation on those.

Dropdown component populated by an API returning orders

Trigger an API on select

Using the previous example, the user can next filter a table of order statuses based on the selected order id. To do so, first create an API that gets the Shipping History for an order from Snowflake. Reference the selected order id from OrderDropdown with {{OrderDropdown.selectedOptionValue}}.

SQL query referencing the selected option of the dropdown component

To ensure this API is called when the dropdown option is selected, configure the dropdown's onOptionChange trigger.

Configure the onOptionChange trigger

Add a Table component below the dropdown and configure the Table Data to bind to {{getShippingHistory.response}}. The table will now update to reflect the order id selected in the dropdown.

Table component populated by a SQL query referencing a dropdown component

Use Python to convert lists to an array of JSON objects

In order to convert a list of labels and values to an array of objects to be used within the Dropdown component, a list comprehension can be used in Python to do this. For example, take the following list of labels and values:

my_labels = ["New York", "Toronto"]
my_values = ["NEW YORK", "TORONTO"]

The following code can be used in a Python step in order to generate an array of JSON objects seen below:

return [{"label": i, "value": j} for i,j in zip(my_labels, my_values)]
"label": "New York",
"value": "NEW YORK"
"label": "Toronto",
"value": "TORONTO"

Component Properties

LabelSet the text label for the dropdown
IconSelect an icon to be displayed in the dropdown input. If the selected option has its own icon, it will override this icon.
OptionsEnter an array of strings or an array of objects where each object has a property that will map to the option label, value and optionally icon. The label and icon will be presented to the user and the value will be returned as the {{dropdown.selectedOptionValue}}
Default selected value stringsChoose the default value
PlaceholderText to inform the user of action like "Select a city"
Enable Multi-selectAllows the user to select multiple options from the dropdown. This can be access via {{dropdown.selectedOptionValues}}
Enable ClearingWhen enabled, allows the user to clear selected options with an x button, values are a boolean
RequiredMakes selecting an option mandatory, values are a boolean
Loading AnimationControls the loading state of the component, values are a boolean
VisibleSet true to show and false to hide. Set dynamically using Javascript with {{}}
VerticalToggles the location of the label, values are a boolean
DisabledDisables user interaction with this component, values are a boolean

Settable Properties

Property Via Form / Via RunJSTypeExample Value
Selected Option / selectedOptionValuestring,Array<string>"TORONTO" , ["TORONTO", "NEW YORK"]

Reference Properties

Properties can be accessed from other frontend components and backend APIs by adding the name of the Dropdown, and dot referencing the property. For a Dropdown named Dropdown1:

Dropdown1.selectedOptionValueReturns a string of the selected value of the dropdown
Dropdown1.selectedOptionValuesReturns an array of the selected values of the dropdown
Dropdown1.searchTextReturns the string value in the search input in the dropdown (often used for server-side typeahead filtering of options)
Dropdown1.optionsReturns an array of the options of the dropdown
Dropdown1.isVisibleReturns the boolean value of the component's visibility (True, if it is visible)
Dropdown1.isDisabledReturns the boolean value of the component's disabled state (True, if it is disabled)


The following events are triggered by user interactions with Dropdown components. Use event handlers to trigger actions in response to user events.

onOptionChangeTrigger an action when the selected option is changed
onSearchTextChangeTriggers an action when a user types in the search box (often used for server-side typeahead filtering of options)
onClearTrigger an action when the dropdown is cleared