Define option lists
Use the option list editor to configure options manually or map data to generate them dynamically.
Many components present a list of options, such as the dropdown in a Select or the menu of a Split Button. Each option contains a number of settings depending on the component—value, label, caption, tooltip, and disabled, and more.
Some components allow you to manually configure each option, or dynamically generate options by mapping data from a query, transformer, or any other source.
Configure options manually
Select Manual mode in the Content settings of the Inspector to configure options using a reorderable list. This mode is suited for lists that contain:
- A small, maintainable number of options.
- Options that are static (e.g., not from an API or database).
- Options used by only one component.
Click + to add an option and configure the available settings, or click an existing option to edit. You can duplicate or delete an option by clicking the ••• icon.
The value (or key for some components) must be unique for each option. If duplicate values are found, only the first option is rendered.
Map data to generate options
Select Mapped mode in the Content settings of the Inspector to generate options from a data source. This is similar to using a .map method on an array: each item in your data source is mapped to each option. This mode is best suited for lists that contain:
- A large number of options.
- Options with a dynamic data source (e.g., from an API or database).
- Options used by multiple components.
Specify a data source
Specify the data to evaluate in the Data source setting. Select from your queries or transformers, or switch to JavaScript mode (fx) to provide an array of values or an object of arrays by key. You can also reference data from anywhere in your app.
Selecting Use JavaScript or Use an array switches the field to an input. Click 𝘧𝑥 to switch back to a dropdown menu.
Configure mapped options
The Mapped options section contains settings that are evaluated for each item in your data source.
Use item to reference the current data source item being evaluated and i to reference the current index. For example, if the items in your data source have an id ([{ id: 1 }, { id: 2 }]), reference this using {{ item.id }} in any setting.
You can test out mapped options by generating sample data from Retool's REST API Generator app.
| Column title | Data type | Description |
|---|---|---|
name | Numbers/Product ID | Product SKU |
quantity | Numbers/Random | Item quantity |
unit_price_cents | Numbers/Random | Item price in cents |
created_at | Dates | Date created |
Click Generate API to generate a test API and save its URL. You can now use this sample data to map options from a query.
First, create a query:
- In the query editor, choose RESTQuery (restapi).
- Select GET as the Action Type.
- In the URL field, enter the endpoint URL you created.
- Click
Run. You should see results from the sample API data.
Next, add and configure a Select component:
- Drag a Select component to the canvas.
- Select Mapped mode.
- Set Data source to the query you created.
You can now map option settings using item.
| Mapped option setting | Evaluated item data |
|---|---|
| Value | {{ item.id }} |
| Label | {{ item.name }} |
| Caption | {{ '$' + (item.unit_price_cents / 100 ).toFixed(2) }} |
| Tooltip | {{ moment(item.created_at).format("MMM Do YY") }} |
| Disabled | {{ item.quantity == 0 }} |
You can use JavaScript almost anywhere in Retool and create logic that provides greater flexibility. In this example, item.unit_price_cents and item.created_at are displayed in a more readable format, and options for products with quantity: 0 are disabled.
If you want to use mapped values outside the component (e.g., in a query or another component), you can use properties like data and selectedItem. For example:
{{ listbox1.data['4'].name }}evaluates to the name of the fifth item.{{ listbox1.selectedItem.name }}evaluates to the name of currently selected item.
Event handlers for mapped options
You can configure the mapped options of certain components, such as Dropdown Button, with event handlers. These event handlers can reference the current item using item or the item's current index using i. For example, you can configure an event handler on a mapped option to display a notification with the button's label with {{ item.label }}.