--- title: "Select List Control" slug: "select-list-control" updated: 2025-12-19T23:16:01Z published: 2025-12-19T23:16:01Z canonical: "docs.processmaker.com/select-list-control" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.processmaker.com/llms.txt > Use this file to discover all available pages before exploring further. # Select List Control The Select List control provides either a checkbox- or multi-select drop-down menu-style control from which the Request participant selects one or more options. Set options that display in this control in one of the following ways: - **Provide each option:** For each option, enter a unique value that represents the option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in the control. Alternatively, provide options in the control in JSON format. - **Reference data in a Request Variable**: Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model. - **Reference a data source in the JSON data model:** Reference data from a [Data Connector](/v1/docs/data-connectors) that displays in this control as its options. Specify the data name, value, and content from the Data Connector. See a [design example](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-using-two-data-connectors). Optionally, use a [PMQL](/v1/docs/search-using-processmaker-query-language-pmql) expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects present in the data object determines the order these options display in the control; options cannot be manually reordered. - **Reference data in a Collection:** Reference data from a Collection and display it as options in this control. Optionally, use a PMQL expression to filter the displayed options in real-time. > [!NOTE] > This control is only available for the following Screen types: > > - Conversational-type > - Form-type > > See [Screen Types](/v1/docs/screens#screen-types). For documented examples of using this control, see: - [Dependent Select List Controls Display Countries and Regions from a Collection](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-from-a-collection). - [Dependent Select List Controls Display Countries and Regions Using Two Data Connectors](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-using-two-data-connectors) - [Data Connector Provides Options in a Select List Control](/v1/docs/example-data-connector-provides-options-in-a-select-list-control) ### Checkbox Functional Description When using the Select List control with checkboxes, the control functions similarly to multiple [Checkbox](/v1/docs/checkbox-control#control-description) controls whereby multiple options may be selected. Unlike using multiple Checkbox controls, the Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/716090a6-5db1-4b8b-b7c4-b690e9f6ee85.png) **Drop-Down Menu Functional Description** When using the Select List control as the drop-down menu, multiple options may be selected one at a time. Selected options have the following attributes: - Each selected option displays in the control. - Each selected option displays in bold-style text in the drop-down menu. Furthermore, a red-colored highlight displays when hovering over a selected option, rather than the default green-colored highlight for deselected options. Follow these guidelines to deselect an item from the Select List control when using the drop-down menu style: - Click the image ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/c5e02bbb-3751-4b2a-ac7b-2d4c7a8fafea.png) for the option to be removed. - Select the option again from the drop-down menu. The Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/3b3365de-6b81-4a49-b471-30316acc2fab.png) --- ## Add the Control to a Screen **Permissions** Your user account or group membership must have the following permissions to design a Screen unless your user account has the **Make this user a Super Admin** setting selected: - Screens: Edit Screens - Screens: View Screens See the [Screens](/v1/docs/permission-descriptions-for-users-and-groups#screens) permissions or ask your Administrator for assistance. Follow these steps to add this control to the [Screen](/v1/docs/screens): 1. [Create a new Form-type or Conversational-type Screen](/v1/docs/create-a-new-screen) or [edit an existing one.](/v1/docs/manage-screens#edit-a-screen) 2. From the Controls Menu on the left, expand the **Input Fields** category, and then locate the **Select List** icon![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fe2d8f66-bda9-4c4f-8573-58cea323464e.png). 3. Drag and drop the control to the Screen Builder canvas. Existing controls in the Screen will adjust positioning based on where you drag the control. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be5e7b31-f420-4142-9e34-22fd6caa6988.png) 4. Configure the Select List control. See [Settings](/v1/docs/select-list-control#inspector-settings). 5. Validate that the control is configured correctly. See [Validate Your Screen](/v1/docs/validate-and-publish-a-screen#validate-a-processmaker-screen). Below is a Select List control where you can select a method to receive notifications. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b4eaa7f1-8585-484a-9c35-fb8c039b869d.png) --- ## Settings The Select List control has the following configurable settings in the Properties Panel: - [**Variable** panel](/v1/docs/select-list-control#variable-panel-settings) - [**Configuration** panel](/v1/docs/select-list-control#configuration-panel-settings) - [**Data Source** panel](/v1/docs/select-list-control#data-source-panel-settings) - [**Design** panel](/v1/docs/select-list-control#design-panel-settings) - [**Advanced** panel](/v1/docs/select-list-control#advanced-panel-settings) --- ### Variable Panel Settings Expand the **Variable** panel from the Properties Panel on the right to configure the following properties: #### Variable Name Edit the default **Variable Name** setting value for this control if necessary. The **Variable Name** setting value represents data in this control during Requests. Ensure that the **Variable Name** setting value is a unique name from other controls in this [Screen](/v1/docs/screens) and contains at least one letter. This is a required setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a95f25f8-0a8d-4679-b48f-b8a17b287ff3.png) Use the **Variable Name** setting value in the following ways: - View the selection made in this control by its **Variable Name** setting's value. The **Data Preview** panel in Preview mode corresponds the option(s) the Request participant selects in the Select List control with that Select List control's **Variable Name** value. The **Variable Name** setting contains the selected option(s) as an array. In the example below, `form_select_list_1` is the **Variable Name** setting's value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/e1d66540-50ac-40a3-ba06-e70731247cf5.png) - Reference this value in [**Visibility Rule** setting expressions](/v1/docs/select-list-control#visibility-rule). - Reference a property from the selected value when the Select List control is of type `object` in the current Screen or with a Nested Screen control. To do so, first reference this control's **Variable Name** value in a [Calculated Property](/v1/docs/calculated-properties), then use this Calculated Property in the target control. As a best practice, do not directly reference the **Variable Name** setting of a Select List control. **Example** Consider the following example. A Select List control with **Variable Name** setting value `account` displays a list of accounts available at your bank. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/56832a25-d716-4b63-a2b5-8d636fc52e45.png) When a user makes a selection, you want to display the selected account in a [Line Input control](/v1/docs/line-input-control) on this Screen. Use the following best practice to reference the value of the Select List control. 1. Insert a Line Input control and set its **Variable Name** value. This example uses the **Variable Name** value `AccountName`. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/332ad30c-952c-4202-ad11-5f1b74b47ef2.png) 2. [Create a Calculated Property](/v1/docs/calculated-properties#add-a-calculated-property) and set the **Property Name** setting to `accountName`. 3. In the **JavaScript** setting, enter the following JavaScript code: ```plaintext if (!this.account) {    // if no account was selected return null    return null; } return this.account.name; ``` ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/3d23a8c2-b8c0-4799-bc8f-033e989345ac.png) See [best practices](/v1/docs/screen-design-best-practices) when editing a Request variable name. #### Label Edit the default label that displays for this control if necessary. **New Select List** is the default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/44c0c004-09d2-4edb-a3c3-2c72f5f56740.png) Ensure that all Select List controls implemented in a Conversational-type Screen contain **Label** setting values. See [Controls in Conversational-Type Screens Require Labels](/v1/docs/screen-design-best-practices#controls-in-conversational-type-processmaker-screens-require-labels). #### Validation Rules Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: **No validation rule(s)**. See [Validation Rules for "Validation" Control Settings](/v1/docs/validation-rules-for-screen-controls). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/836641b6-50cc-4141-9651-5a920e6e16f2.png) Follow these steps to add a validation rule to this control: 1. Access the [**Variable** panel for this control](/v1/docs/select-list-control#variable-panel-settings) while in Design mode, and then locate the **Validation Rules** setting. 2. Click the **Add Rule** button. The **Select** drop-down menu displays. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/818cf2c1-735a-498d-8e54-2b2a10aae168.png) 3. Select the rule that this control validates against. 4. Click **Save**. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule. 5. Enter the parameter settings that this control uses to validate against. See [Validation Rule Settings](/v1/docs/select-list-control#validation-rules), and then locate the validation rule for its parameters. Follow these steps to edit a validation rule for this control: 1. Access the [**Variable** panel for this control](/v1/docs/select-list-control#variable-panel-settings) while in Design mode, and then locate the **Validation Rules** setting. 2. Click the **Edit** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/4973b508-0d93-436a-9ede-06c8b90ca173.png) for the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays. 3. Edit the parameter settings that this control uses to validate against. See [Validation Rule Settings](/v1/docs/select-list-control#validation-rules), and then locate the validation rule for its parameters. Follow these steps to delete a validation rule for this control: 1. Access the [**Variable** panel for this control](/v1/docs/select-list-control#variable-panel-settings) while in Design mode, and then locate the **Validation Rules** setting. 2. Click the **Delete** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/15377619-f633-4159-82f7-81660ff0584e.png) for the validation rule to delete. A message displays to confirm deletion of the validation rule. 3. Click **Delete**. #### Make Required Select to indicate that this control is required. This option is not selected by default. This is a quick way to add the [Required](/v1/docs/validation-rules-for-screen-controls#required) validation rule. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/78af3a5b-7b41-4329-a0e9-88c490cbacf1.png) In the Screen preview or during a Request, the control displays with a red-colored asterisk. If you submit the Screen without selecting this required Checkbox, this control displays **Field is required** in red-colored text. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/9ff42d42-7dd0-4500-94f3-b54f9aefc65d.png) #### Read Only Select to indicate that this control cannot be edited. This option is not selected by default. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/3907afd4-ffc4-41aa-abd9-3a5aac6cec1a.png) --- ### Configuration Panel Settings Expand the **Configuration** panel from the Properties Panel on the right to configure the following properties: #### Placeholder Text Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a8c02e15-60eb-4384-bf21-31343c2f9ab5.png) #### Helper Text Enter text that provides additional guidance on this control's use. This setting has no default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/98c8b570-8666-496c-9cdc-a32ae1e3c250.png) --- ### Data Source Panel Settings Expand the **Data Source** panel from the Properties Panel on the right to select one of the following methods to specify options that display in the Select List control: - [Provide options](/v1/docs/select-list-control#provide-options): Enter a unique value that represents each option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in this control. Alternatively, provide options in this control in JSON format. - [Request data](/v1/docs/select-list-control#reference-request-data): Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model. During the in-progress Request, the Select List control references a specified data array and object in the Request's JSON data model to display its values as options in that control. The order that data objects are in the Request's JSON data model determines the order these options display in the control; options cannot be manually reordered. See the following related topics: - [Select List Controls: Avoid Using Request Data for Options in Which JSON Objects May Dynamically Change](/v1/docs/screen-design-best-practices#select-list-controls-avoid-using-request-data-for-options-in-which-json-objects-may-dynamically-chan) - Example: [Dependent Field Design Example Using Select List Controls](/v1/docs/select-list-control#dependent-field-design-example-using-select-list-controls). - [Data Connector](/v1/docs/select-list-control#reference-a-data-connector): Reference the data from a Data Connector's [Endpoint](/v1/docs/data-connectors#what-is-an-endpoint) as options in this control. These Endpoints a [Data Connector](/v1/docs/data-connectors) references may be Application Program Interface (API) endpoints, Collection records, or other data source endpoints. During the in-progress Request, when the Select List control references data from the Data Connector, the control maps the Data Connector data to a specified JSON data array, variable or key name, or data object to become part of that Request's data. Data maps to the JSON data array in the same order it is retrieved from the Data Connector. Optionally, use a [PMQL](/v1/docs/search-using-processmaker-query-language-pmql) expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects return from the Data Connector determines the order these options display in the control; options cannot be manually reordered. See Example: [Dependent Select List Controls Display Countries and Regions](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-using-two-data-connectors). - [Collection](/v1/docs/select-list-control#reference-a-collection): Reference data saved in a [Collection](/v1/docs/collections) and display records from a Collection column. Optionally, use a [PMQL](/v1/docs/search-using-processmaker-query-language-pmql) expression to limit which data to use as options based on the PMQL expression's criteria. For an example, see [Example: Dependent Select List Controls Display Countries and Regions from a Collection](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-from-a-collection). #### Provide Options See the following procedures how to provide options for a Select List control. - [Add an Option](/v1/docs/select-list-control#add-an-option) - [Edit an Option](/v1/docs/select-list-control#edit-an-option) - [Delete an Option](/v1/docs/select-list-control#delete-an-option) - [Sort the Order of the Option](/v1/docs/select-list-control#Sort-the-Order-of-the-Option) - [Provide Options Using a JSON Schema](/v1/docs/select-list-control#Provide-Options-Using-a-JSON-Schema) - [How Options Display](/v1/docs/select-list-control#How-Options-Display) - [Set to Allow Multiple Selection](/v1/docs/select-list-control#Set-to-Allow-Multiple-Selections) ##### Add an Option Follow these steps to add an option that displays in this control using Screen Builder: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then locate the **Data Source** setting. 2. From the **Data Source** drop-down menu, select **Provide Values** if this setting is not selected. This is the default setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 3. Ensure that the **Options** list label displays. If the **JSON Data** option displays, click the **Edit as Option List** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/88db763f-afcc-45ec-bd69-e815a3a1b892.png) 4. Click the icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/2e359507-ad30-468c-815b-fabe72abbdc0.png) beside the **Options** list label. The **Add Option** screen displays. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/8fe436df-9058-4b70-973e-6f92c7190614.png) 5. In the **Value** setting, enter a value to represent the option in the Request data. This value must be unique from other values in this control. If the value is not unique to other **Value** settings in this control, the following message displays: **An item with the same key already exists**. 6. In the **Content** setting, enter the option that displays in this control. 7. Click **Save**. The option displays below the **Options** list label. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a899c64b-7807-4e05-af39-3b4d5a47c32f.png) ##### Edit an Option Follow these steps to edit an option that displays in this control using Screen Builder: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then ensure that the **Data Source** setting uses the **Provide Values** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 2. Ensure that the **Options** list label displays. If the **JSON Data** option displays, click the **Edit as Option List** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/60f32e4f-3cf2-4713-b70a-33ee974669ae.png) 3. Click the ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b2863b74-108b-4897-a1b3-8f382c28e7cb.png) icon for an option to edit its settings. The **Edit Option** screen displays. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/af7f0c0f-faa2-442d-af5c-acece6b13791.png) 4. In the **Value** setting, edit the value to represent the option in the JSON data model during in-progress Requests for Processes that use this Screen as necessary. This value must be unique from other values in this control. If the value is not unique to other **Value** settings in this control, the following message displays: **An item with the same key already exists**. 5. In the **Content** setting, edit the option that displays in this control as necessary. 6. Click **Update**. The edited option displays below the **Options** list label. ##### Delete an Option Follow these steps to delete an option from in this control using Screen Builder: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then ensure that the **Data Source** setting uses the **Provide Values** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 2. Ensure that the **Options** list label displays. If the **JSON Data** option displays, click the **Edit as Option List** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/60f32e4f-3cf2-4713-b70a-33ee974669ae.png) 3. Click the ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/66916c35-96df-4075-a4f9-e09e95a4c9c3.png) icon for the option to be deleted from this control. A message displays to confirm deletion of the option. 4. Click **Delete**. ##### Sort the Order of the Options Follow these steps to sort the order of the options that display in this control using Screen Builder: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then ensure that the **Data Source** setting uses the **Provide Values** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 2. Ensure that the **Options** list label displays. If the **JSON Data** option displays, click the **Edit as Option List** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/60f32e4f-3cf2-4713-b70a-33ee974669ae.png) 3. Drag the![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a2a7d854-6c9b-497c-af6b-c4c2da1b54ce.png)icon for each option up or down to sort the order they display in this control as necessary. ##### Provide Options Using a JSON Schema Follow these steps to provide options that display in this control using a JSON schema: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then locate the **Data Source** setting. 2. From the **Data Source** drop-down menu, select **Provide Values** if this setting is not selected. This is the default setting. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 3. Click the **Edit as JSON** option below the **Options** list label. If the **JSON Data** setting displays, skip this step. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/89cb96e1-3bbf-4afd-8c34-b0d83cc12c7c.png) The **JSON Data** setting displays. If a valid JSON schema has been configured previously, the **JSON Data** setting displays the JSON. Otherwise, this setting is empty. 4. Click the icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/bf7eea82-1fe1-4498-9b8e-6df9f91adc2e.png) beside the **JSON Data** option. The **Script Config Editor** displays. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/2cfab1f5-9693-46c2-81e7-d1b8b2366ff4.png) 5. Enter your control options in the order they are to display in this control using JSON format. Use the scroll panel to the right of the JSON to scroll to different sections of the JSON if necessary. This is useful especially when you are editing a long JSON. 6. Click **Close** or the **Close** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fe34a4bb-4c55-49d3-b3f9-15e4f3504d24.png). The control options are saved. ##### How Options Display Follow these steps to set how the options display: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then ensure that the **Data Source** setting uses the **Provide Values** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 2. Click the **Allow multiple selections** setting to allow multiple options to be selected from this control. Otherwise, only one option can be selected. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fa69b3e3-318a-40ac-905b-a6c132dfe351.png) 3. From the **Render Options As** drop-down menu, select one of the following options: - **Dropdown/Multiselect:** Select the **Dropdown/Multiselect** option to display the control as a drop-down menu. - **Radio/Checkbox Group:** Select the **Radio/Checkbox Group** option to display the control as a group of checkboxes. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Select List - Show Control As.png) ##### Set to Allow Multiple Selections Follow these steps to set whether multiple selections can be selected from this control: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode, and then ensure that the **Data Source** setting uses the **Provide Values** option. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/be8d2e85-1700-4da0-bc5b-72a4f1228e73.png) 2. Click the **Allow multiple selections** setting to allow multiple options to be selected from this control. Otherwise, only one option can be selected. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fa69b3e3-318a-40ac-905b-a6c132dfe351.png) > [!NOTE] > Best Practice When Configuring a Select List Control Within a Loop Control > > Make note of [best practices](/v1/docs/screen-design-best-practices) when configuring a Select List control's options when that control is within a [Loop](/v1/docs/loop-control) control. When referencing a [JSON array](/v1/docs/json#json-arrays) from a data source, configure the Select List control to reference the [JSON object](/v1/docs/json#json-objects) containing the JSON array and not its values. Then duplicate the JSON array in the Loop control. See [Duplicate the JSON Array in a Select List Control Used in a Loop Control](/v1/docs/screen-design-best-practices#duplicate-the-json-array-in-a-select-list-control-used-in-a-loop-control). > > > > Best Practice When Editing a Collection Using a Select List Control in a Loop Control > > Make note of [best practices](/v1/docs/screen-design-best-practices) when editing a Collection record using a [Select List control](/v1/docs/select-list-control) in a [Loop control](/v1/docs/loop-control), configure the Select List control's [**Type of Value Returned** setting](/v1/docs/select-list-control#reference-request-data) with the **Single Value** option. See [Use Single Value instead Object in a Select List](/v1/docs/screen-design-best-practices#use-single-value-instead-object-in-a-select-list). > > Make note of [practices to avoid when referencing Request data for the options in a Select List control](/v1/docs/screen-design-best-practices#select-list-controls-avoid-using-request-data-for-options-in-which-json-objects-may-dynamically-chan). #### Reference Request Data Follow these steps to reference data from the in-progress Request as options in this control: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode. 2. From the **Data Source** drop-down menu, select **Request Data**. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a68575d2-1ea7-42bb-8fff-8b465421ab8d.png) 3. In the **Options Variable** setting, enter from which Request variable, based on its **Variable Name** setting value, to use as options for this control. The Request variable from which to use as options must be an array. The options in the Select List control display in the same order as the Request variable lists items in its array. Optionally, use [mustache syntax](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/mustache.5(11).html) to indicate the Request variable name, especially if each option in this control derives from combining multiple properties within an array where each of its items contains one or more objects. **response** is the default setting. See [Dependent Field Design Example Using Select List Controls](/v1/docs/select-list-control#dependent-field-design-example-using-select-list-controls). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b718c075-909c-4cc8-8b52-7c7795277548.png) 4. In the **Option Label Shown** setting, enter the JSON object key name from within the JSON array containing the Request variable from which to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the **Option Label Shown** setting. Use [JSON dot notation](/v1/docs/json#json-dot-notation) as necessary. For example, consider the following JSON array within Request data named `accountTypes` that contains two JSON objects, both of which their key names are `type`: `    "accountTypes": [ ` `      {"type": "Life"}, ` `      {"type": "Medical"} ` `    ]` To reference both values from the key name `type` as options in the Select List control, use the following JSON dot notation in the **Option Label Shown** setting: `data.accountTypes`. The JSON array must contain JSON objects composed of key names and corresponding values, not just values like the following: `    "accountTypes": [ ` `      "Life", "Medical" ` `    ]` Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array. **content** is the default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/5c6f61ed-3e75-4fc0-9e75-f9386586486b.png) 5. From the **Show Control As** drop-down menu, select one of the following options: - **Dropdown/Multiselect:** Select the **Dropdown/Multiselect** option to display the control as a drop-down menu. - **Radio/Checkbox Group:** Select the **Radio/Checkbox Group** option to display the control as a group of checkboxes. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/358af05f-0592-4149-b236-101151da2759.png) 6. Select the **Allow multiple selections** option to allow multiple options to be selected from this control. Otherwise, only one option can be selected. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fa69b3e3-318a-40ac-905b-a6c132dfe351.png) 7. From the **Type of Value Returned** drop-down menu, select one of the following options: - **Single Value:** Select the **Single Value** option to indicate that only a part of the JSON object specified from the **Option Label Shown** displays as each option in this control. [As a best and general practice, use single-value JSON objects](/v1/docs/screen-design-best-practices#use-single-value-instead-of-object-if-select-list-control-options-may-change). - **Object:** Select the **Object** option to indicate that the entire JSON object within each item of the array displays as each option in this control. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/5540f0d9-49e2-4a58-8fd5-1f3eb35bd3cc.png) 8. If the **Single Value** option from the **Type of Value Returned** setting is selected, the **Variable Data Property** setting displays. In the **Variable Data Property** setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the **Variable Data Property** setting. Use [JSON dot notation](/v1/docs/json#json-dot-notation) as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use mustache syntax to indicate the JSON key name from within the JSON array. **value** is the default value. See [Dependent Field Design Example Using Select List Controls](/v1/docs/select-list-control#dependent-field-design-example-using-select-list-controls). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/cfd47fd2-337c-47fc-aa09-541eff28dbfc.png) #### Reference a Data Connector Follow these steps to reference data from a [Data Connector](/v1/docs/data-connectors) as options in this control: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode. 2. From the **Data Source** drop-down menu, select **Data Connector**. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/c030f436-2e1a-4291-bcbd-b4190863e172.png) 3. In the **Options Variable** setting, enter the name of the JSON array containing the API's JSON response from which to reference its objects as options that display in this control after the Data Connector's Resource interacts with the API endpoint. The name of the JSON array is called `response` by default. Use [JSON dot notation](/v1/docs/json#json-dot-notation) as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. **response** is the default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b718c075-909c-4cc8-8b52-7c7795277548.png) 4. From the **Show Control As** drop-down menu, select one of the following options: - **Dropdown/Multiselect:** Select the **Dropdown/Multiselect** option to display the control as a drop-down menu. - **Radio/Checkbox Group:** Select the **Radio/Checkbox Group** option to display the control as a group of checkboxes. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/9c4ede16-91b7-484c-86e5-2f3c8feac9ef.png) 5. Select the **Allow multiple selections** option to allow multiple selections from this control. Otherwise, only one option can be selected. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/fa69b3e3-318a-40ac-905b-a6c132dfe351.png) 6. From the **Type of Value Returned** drop-down menu, select one of the following options: - **Single Value:** Select the **Single Value** option to indicate that only a part of the JSON object specified from the Option Label Shown displays as each option in this control. - **Object:** Select the **Object** option to indicate that the entire JSON object within each item of the array displays as each option in this control. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/5540f0d9-49e2-4a58-8fd5-1f3eb35bd3cc.png) 7. If the **Single Value** option from the **Type of Value Returned** setting is selected, the **Value** setting displays. In the **Value** setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the **Value** setting. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use [mustache syntax](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/mustache.5(11).html) to indicate the JSON key name from within the JSON array. **value** is the default setting. See [Dependent Field Design Example Using Select List Controls](/v1/docs/select-list-control#dependent-field-design-example-using-select-list-controls). ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b5a9bb73-3a8b-4df8-a9e1-44cd8ba8d256.png) 8. In the **Content** setting, enter the JSON object key name from within the JSON array containing the JSON response to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the **Content** setting. Use JSON dot notation as necessary. Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array. **content** is the default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a7e9212f-b99c-46eb-9ba3-215ad783145b.png) 9. From the **Data Connector** drop-down menu, select from which Data Connector to reference as a data source. If a Data Connector does not exist, this setting has no options. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/f5041ffc-ac99-4545-ac3c-ae788e03b792.png) 10. From the **End Point** drop-down menu, select which Resource to reference from the selected Data Connector. A Resource is a Data Connector asset with which to interact with a data source, also called an End Point. These Resources are configured from the Data Connector itself. Depending on the Data Connector selected from the **Data Connector Name** drop-down menu, these Resources may reference Application Program Interface (API) endpoints, Collection records, or other data source endpoints. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/c4386d71-91ea-42d9-bc11-a287ca65b6eb.png) 11. In the **PMQL** setting, optionally enter a [PMQL](/v1/docs/search-using-processmaker-query-language-pmql#overview) expression to filter which data in the JSON data array to display as options in this control based on which JSON objects in that array meet the PMQL expression's criteria. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/907cc5c2-15ba-47f6-be83-49d4b28b2512.png) Consider the following example of doctors who work in a clinic. ```json doctors = [    {id: 1, name: 'Adam Ardin', gender: 'male'},    {id: 2, name: 'Amanda Creek', gender: 'female'},    {id: 3, name: 'Lucy Morales', gender: 'female'},    {id: 4, name: 'Mindy Smith', gender: 'female'},    {id: 5, name: 'Toby Tomlinson', gender: 'male'} ] ``` Use the following settings to reference this data array as options for this control: - **Element Name:** `doctors` - **Value:** `id` - **Content:** `name` Suppose that a new patient at the clinic indicates that she wants to see a female doctor. To filter doctors from this JSON data array who are female in the clinic so that only those objects display as options in a Select List control, use the following PMQL expression in the **PMQL** setting of that control: `gender = "female"` #### Reference a Collection Follow these steps to reference data from a Collection as options in this control: 1. Access the [**Data Source** panel for this control](/v1/docs/select-list-control#data-source-panel-settings) while in Design mode. 2. From the **Data Source** drop-down menu, select **Collection**. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/341ac730-5daf-40ad-b5f7-fc91d6b8e02f.png) 3. From the **Collection** drop-down menu, select the name of the Collection from which to retrieve data. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/781b1cfc-f39c-46c2-af44-a0cdea03f26c.png) 4. From the **Label** drop-down menu, select the name of the Collection column that contains the data to be displayed as options in the Select List control. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/2f2172a0-0107-498a-8e6e-78fd3baccc75.png) 5. From the **Value** drop-down menu, select the name of the Collection column that contains the data to be saved into [Request data](/v1/docs/request-data-and-json) when a user makes a selection. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/4b12d138-c767-4919-843d-bfbc94f0c553.png) The **Label** and **Value** drop-down menus can have the same or different Collection columns selected. Consider an example of a Collection with columns `City Name` and `Zip Code`. The Select List control can be configured in the following ways: 1. Selecting `City Name` in **Label** and **Value** displays the name of all cities in the Select List control and save the name of the selected city in Request data. 2. Selecting `City Name` in **Label** and `Zip Code` in **Value**, displays a list of cities, but saves the Zip Code of the selected city in Request data. 6. In the **PMQL** setting, optionally enter a [PMQL](/v1/docs/search-using-processmaker-query-language-pmql#overview) expression to filter the data being retrieved from the Collection. If a filter criteria is specified here, the Select List control dynamically filters in real-time based on the specified PMQL expression. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/7f25d096-436e-430b-9b0b-b7887566aab8.png) 7. Select the **Ignore** **duplicates** **in** **list** option to display repeating data only once in the Select List control. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/d14336bd-08b6-4158-a050-fd93b42f6085.png) See [Example: Dependent Select List Controls Display Countries and Regions from a Collection](/v1/docs/example-dependent-select-list-controls-display-countries-and-regions-from-a-collection). --- ### Design Panel Settings Expand the **Design** panel from the Properties Panel on the right to configure the following properties: #### Text Color Select the text color that displays for this control. Optionally, click the **Clear Color Selection** option to remove the selected color. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/724214e2-a9ac-4eae-bee7-5a673cdff25b.png) #### Background Color Select the background color that displays for this control. Optionally, click the **Clear Color Selection** option to remove the selected color. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/e5dd878c-5584-4c7f-9750-e2e2c3dd4f2b.png) --- ### Advanced Panel Settings Expand the **Advanced** panel from the Properties Panel on the right to configure the following properties: #### Default Value Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a [Request variable](/v1/docs/request-variable) in the **Default Value** setting, consider the following: - If the Request variable is empty, the control does not display any value by default. - When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control. - Any further changes to the Request variable do not affect the default value of the control. The **Default Value** setting supports using Request variables in [mustache syntax](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/mustache.5(11).html). For example, if the **Default Value** setting is `{{ FirstName }} {{ LastName }}` from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request. There are two ways to enter the default value this control displays. --- **Default Value As A Text** Enter the default value as text or a Request variable in mustache syntax. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/901823b6-9691-4b37-8a53-4b449604558a.png) When the Select List control is configured with [Provide Options](/v1/docs/select-list-control#provide-options), the **Default Value** setting compares numerical values as a string. If the Select List is configured with [Provide Options Using a JSON Schema](/v1/docs/select-list-control#provide-options-using-a-json-schema), take care to enclose the numerical values in quotation marks (such as `"1"`) because this can cause errors when comparing against the **Default Value** setting value. ```json [    {        "value": "1",        "content": "Joyce"    },    {        "value": "2",        "content": "Natty"    },    {        "value": "3",        "content": "Franny"    },    {        "value": "4",        "content": "Beatty"    }, ] ``` If you need to compare default values other than a String-type value, enter the default value using JavaScript. --- **Default Value As A Script** Enter the default value as JavaScript, especially if a Calculated Property might change this default value setting. Ensure to use the `this.` JavaScript keyword preceding the Screen control reference. Example: `this.FullName` when `FullName` is the **Variable Value** setting value for the control to set its default value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/832eab95-82db-4879-8fa9-6097dd88f2f2.png) As opposite to the default setting, the JavaScript setting accepts values different to a String. Then if the Select List is configured with [Provide Options Using a JSON Schema](/v1/docs/select-list-control#provide-options-using-a-json-schema), then enter the Default Value as in the JSON schema. For example enter `return 2;`if the JSON values are integers like: ```json [    {        "value": 1,        "content": "Joyce"    },    {        "value": 2,        "content": "Natty"    },    {        "value": 3,        "content": "Franny"    },    {        "value": 4,        "content": "Gan"    }, ] ``` #### Visibility Rule Specify an expression that indicates the condition(s) under which this control displays. See [Expression Syntax Components](/v1/docs/feel-expression-syntax#show-or-hide-screen-builder-controls). If this setting does not have an expression, then this control displays by default. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b42384a8-e5db-4c81-9143-e579e62e0d99.png) For example, this control displays if the variable value **tip** is **1**. For a detailed example of the Visibility Rule setting, see [Show or Hide Controls Based on Button Selection](/v1/docs/example-show-or-hide-controls-based-on-button-selection). Note the following regarding how to use visibility rules: - To make this control hidden until another control contains a value, enter the **Variable Name** setting value of that control to this control's **Visibility Rule** setting. - [Visibility rules override custom CSS settings](/v1/docs/screen-design-best-practices#visibility-rules-override-custom-css-settings). #### Device Visibility Select on which device types this control displays: - **Desktop:** The control displays only on desktop devices. Enable the **Show for Desktop** toggle key. - **Mobile:** The control displays only on mobile devices. Enable the **Show for Mobile** toggle key. - **Both:** The control displays on both desktop and mobile devices. Both toggle keys are enabled by default. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b2d3123d-bdc1-4bfb-890b-0ce07ed6b359.png) #### CSS Selector Name Enter the value to represent this control in custom CSS syntax when in [Custom CSS](/v1/docs/custom-css#add-custom-css-to-a-processmaker-screen) mode. As a best practice, use the same **CSS Selector Name** value on different controls of the same type to apply the same custom CSS style to all those controls. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/37cc0b3a-ca5b-46e9-9a55-cceca4b86cbe.png) Then, use this name in the [Custom CSS](/v1/docs/custom-css#apply-css-to-specific-processmaker-screen-controls) feature to apply CSS styling to this control as follows: ```css [selector='Submit Form'] {    color: blueviolet; } ``` See the following best practices regarding custom CSS in Screens: - [Editing a CSS name to represent this control in custom CSS syntax](/v1/docs/screen-design-best-practices#css-selector-naming-best-practice) - [Visibility rules override custom CSS setting](/v1/docs/screen-design-best-practices#visibility-rules-override-custom-css-settings) --- ### Accessibility Panel Settings The **Accessibility** panel centralizes settings that enhance screen-reader compatibility and overall usability. ARIA Label setting persists through import, copy/paste, versioning, and upgrades, supporting a more inclusive and standards-aligned Screen Builder experience. #### Aria Label Enter the string that provides a text alternative to this control for the following purposes: - Assistive technology, such as screen readers, read the **Aria Label** setting value. - This control has a visual indication of its purpose, such as a control that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication. The **Aria Label** setting value replaces the [**Label** setting](/v1/docs/select-list-control#label) value. For example, if a control has both a **Label** setting value and an **Aria Label** setting value, assistive technology only uses the **Aria Label** setting value. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/5daf8688-0555-40ff-aa50-87daf91dd716.png) #### Tab Order Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation. [See best practices for setting the tab order for a Screen's controls](/v1/docs/screen-design-best-practices#tab-order-for-keyboard-navigation). Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen. ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/1a96177a-dc9b-42c6-9fcc-42251734cfe9.png)