Select

A selection from predefined values

Specification

multiple

• Type: Boolean

• Default: False

• If true, multiple selections are allowed.

sort

• Type: String

• Allowed values: text or number

• Items are unsorted by default. However, you can sort them by using this option.

grouped

• Type: Boolean

• If true, options can be grouped by using grouped options syntax.

[
    {
        label: "Group",
        options: [
            {
                label: "Option",
                value: 1
            }
        ]
    }
]

options

• Available types:

Type	Specification
array	An array of options for this Select. Example: [ { label: "Option", value: 1 } ]
string	Specifies an Options RPC URL, that will be called to retrieve dynamic options for this selection.
object	Allows specifying the detailed configuration of options and nested parameters for this Select field.

• Available parameters:

Parameter	Type	Specification
store	array	Specifies options for the select field.
store	string	Specifies an options RPC URL, that will be called to retrieve dynamic options for the select.
label	string	Specifies the name of a property that will be used as the label of an option.
value	string	Specifies the name of a property that will be used as the value of an option.❗ Value cannot be null. ❗
placeholder	string	Specifies the label which will be shown when no option is selected. Available parameters: label (string) Specifies the label which will be shown when no option is selected. nested (array)Specifies an array of nested parameters that are shown when no option is selected.
placeholder	object	Specifies a detailed configuration of a placeholder. Available parameters: label (string) Specifies the label which will be shown when no option is selected. nested (array)Specifies an array of nested parameters that are shown when no option is selected.
nested	array	Specifies an array of nested parameters that are shown when an option is selected. When the select is multiple, the nested parameters will be generated and displayed for selected options.
nested	string	Specifies an RPC URL, that will be called to retrieve dynamic nested options.

mode

• Type: String.

• Accepted values: edit or choose.

• Specifies the initial mode of select, when editable is true.

validate

• Type: Object or Boolean.

• Specifies parameter validation.

When set to false, the validation against the provided options gets disabled for manual input.

Manual Input Mode (default behavior)

Example of Validation

Manual Input Mode (validation disabled)

Example of Validation with Mapping Mode

Selection Mode

Example of Missing Validation

• Available parameters:

Parameter	Type	Specification
maxItems	number	Specifies the maximal count of selected items when multiple is true.
minItems	number	Specifies the minimal count of selected items when multiple is true.

spec

• Type: Object.

• Used for validation is editable is true. If not specified, the value will be passed as is and no validation is performed.

• Available parameters:

Parameter	Type	Specification
type	string	Specifies a data type of value from the select, which will be validated. This is usable for example when your API returns numerical IDs in strings but you want them to be typed as numbers in the output of your module.

dynamic

• Type: Boolean

• Default: False

• Defines whether a mapped value in the select should be validated against the option values. If true, the value is treated as a dynamic and validation is disabled. The value is set to true automatically if select options are generated using RPC.

mappable

• Type: Boolean or Object

  • Set to false to make field non-mappable.

  • If Object, it specifies the detailed configuration of the mapping toggle.

• Available parameters:

Parameter	Type	Specification
help	string	Alternative help text is shown only when the mappable toggle is turned on.

editable (deprecated)

• Type: Boolean or Object

• If Boolean and set to true , the value of select can be edited (or mapped) manually.

• If Object, specifies a detailed configuration for editable.

• Available parameters:

Parameter	Type	Specification
enabled	boolean	If set to true , the value of select can be edited (or mapped) manually.
help	string	Alternative help text is shown only when the mappable toggle is turned on.

Examples

Basic Select

A basic select with few options which can't be changed manually.

Appearance

Example of Basic Select

Source

[
	{
		"name": "select",
		"label": "Size",
		"type": "select",
		"options": [
			{
				"label": "Small",
				"value": "s"
			},
			{
				"label": "Medium",
				"value": "m"
			},
			{
				"label": "Large",
				"value": "l"
			}
		]
	}
]

Select with Grouped Options

By enabling grouped options, you can sort options into groups.

Appearance

Example of Grouped Options

Source

[
	{
		"name": "select",
		"label": "Size",
		"type": "select",
		"grouped": true,
		"options": [
			{
				"label": "Men",
				"options": [
					{
						"label": "Small",
						"value": "ms"
					},
					{
						"label": "Medium",
						"value": "mm"
					},
					{
						"label": "Large",
						"value": "ml"
					}
				]
			},
			{
				"label": "Women",
				"options": [
					{
						"label": "Small",
						"value": "ws"
					},
					{
						"label": "Medium",
						"value": "wm"
					},
					{
						"label": "Large",
						"value": "wl"
					}
				]
			}
		]
	}
]

Multiple Choice

You can turn on multiple choice by setting multiple to true.

Appearance

Example with Multiple Choice

Source

[
	{
		"name": "select",
		"label": "Meal",
		"type": "select",
		"options": [
			{
				"label": "Breakfast",
				"value": "breakfast"
			},
			{
				"label": "Lunch",
				"value": "lunch"
			},
			{
				"label": "Dinner",
				"value": "dinner"
			}
		],
		"multiple": true
	}
]

Output

["breakfast","dinner"]

Multiple Choice with Validation

You can validate the number of selected options by using validate object.

Appearance

Validation Error after Atempt to Save the Module

Source

[
	{
		"name": "select",
		"label": "Preferred means of transport",
		"type": "select",
		"options": [
			{
				"label": "Tram",
				"value": "tram"
			},
			{
				"label": "Bus",
				"value": "bus"
			},
			{
				"label": "Underground",
				"value": "underground"
			},
			{
				"label": "Boat",
				"value": "boat"
			},
			{
				"label": "Plane",
				"value": "plane"
			},
			{
				"label": "Train",
				"value": "train"
			}
		],
		"multiple": true,
		"validate": {
			"minItems": 1,
			"maxItems": 3
		}
	}
]

Mappable Select with Help

You can display a custom help message when the mappable toggle is turned on.

Appearance

Example of Help Which Displays after Switching to Maping Mode

Source

[
	{
		"name": "select",
		"type": "select",
		"label": "Size",
		"options": [
			{
				"label": "Small",
				"value": "s"
			},
			{
				"label": "Medium",
				"value": "m"
			},
			{
				"label": "Large",
				"value": "l"
			}
		],
		"mappable": {
			"help": "If not sure, call your mother."
		}
	}
]

Preselected Value

By setting default, you can set a preselected value. The value of desired option and default has to match to preselect the correct option properly.

Appearance

Preselected Value "Medium"

Source

[
	{
		"name": "select",
		"type": "select",
		"label": "Size",
		"options": [
			{
				"label": "Small",
				"value": "s"
			},
			{
				"label": "Medium",
				"value": "m"
			},
			{
				"label": "Large",
				"value": "l"
			}
		],
		"default": "m"
	}
]

Placeholder

You can choose what to display when no option is selected by specifying a placeholder. Notice that you have to put options inside the store array to make this work.

Appearance

Example of Placeholder

Source

[
	{
		"name": "select",
		"type": "select",
		"label": "Size",
		"options": {
			"store": [
				{
					"label": "Small",
					"value": "s"
				},
				{
					"label": "Medium",
					"value": "m"
				},
				{
					"label": "Large",
					"value": "l"
				}
			],
			"placeholder": "Select your T-shirt size"
		}
	}
]

Nested Options

To display a set of fields only when an option is selected, you may use nested options.

Appearance

Nested Options Size and Notes

Source

[
	{
		"name": "pizza",
		"type": "select",
		"label": "Pizza",
		"options": {
			"store": [
				{
					"label": "Salami",
					"value": "salami"
				},
				{
					"label": "Margheritta",
					"value": "margheritta"
				},
				{
					"label": "Mexico",
					"value": "mexico"
				}
			],
			"nested": [
				{
					"name": "size",
					"type": "select",
					"label": "Size",
					"options": [
						{
							"label": "Small",
							"value": 32
						},
						{
							"label": "Large",
							"value": 45
						}
					]
				},
				{
					"name": "notes",
					"type": "text",
					"label": "Notes"
				}
			]
		}
	}
]

Nested Fields for Specific Options

You may want to display certain fields only when a specific option is selected. In this case, you can nest fields under a specific option.

Appearance

Nested Field for Phone Support Option

Nested Field for Email Support Option

Source

[
	{
		"name": "plan",
		"type": "select",
		"label": "Support plan",
		"options": [
			{
				"label": "Email support",
				"value": "email",
				"nested": [
					{
						"type": "email",
						"label": "Email",
						"name": "email"
					}
				]
			},
			{
				"label": "Phone support",
				"value": "phone",
				"nested": [
					{
						"type": "text",
						"label": "Phone number",
						"name": "phone"
					}
				]
			}
		]
	}
]

Select Under Select

This is a special case of nested options, which is usable for example for specifying a category and its subcategory.

Appearance

Select under Sport Option

Select under Music Option

Source

[
	{
		"name": "category",
		"type": "select",
		"label": "Category",
		"options": {
			"store": [
				{
					"label": "Sport",
					"value": "sport",
					"nested": [
						{
							"type": "select",
							"label": "Subcategory",
							"name": "subcategory",
							"options": [
								{
									"label": "Hockey",
									"value": "hockey"
								},
								{
									"label": "Football",
									"value": "football"
								}
							]
						}
					]
				},
				{
					"label": "Music",
					"value": "music",
					"nested": [
						{
							"type": "select",
							"label": "Subcategory",
							"name": "subcategory",
							"options": [
								{
									"label": "Pop",
									"value": "pop"
								},
								{
									"label": "Rock",
									"value": "rock"
								}
							]
						}
					]
				}
			]
		}
	}
]

Mode Edit as default

When your select is editable, you can set the default mode edit.

Appearance

Default Mode Edit

Source

[
	{
		"name": "choosable",
		"type": "select",
		"label": "Choosable",
		"editable": true,
		"options": [
			{
				"label": "Option A",
				"value": "a"
			},
			{
				"label": "Option B",
				"value": "b"
			}
		]
	},
	{
		"name": "editable",
		"type": "select",
		"label": "Editable",
		"editable": true,
		"mode": "edit",
		"options": [
			{
				"label": "Option A",
				"value": "a"
			},
			{
				"label": "Option B",
				"value": "b"
			}
		]
	}
]

Nested RPCs

You can nest RPCs when retrieving nested fields dynamically. The nested RPC will receive id parameter automatically.

Source

[
   {
       "name": "id",
       "type": "select",
       "mode": "edit",
       "options": {
           "store": "rpc://listBoards",
           "nested": [
               {
                   "name": "member_id",
                   "type": "select",
                   "label": "Member",
                   "options": "rpc://getMemberIdBoard",
                   "required": true
               }
           ]
       },
       "label": "Board ID",
       "required": true
   }
]

Placeholder Nested Fields (deprecated)

To display some fields only when no option is selected, you can use the placeholder object.

Appearance

Example of Placeholder in a Nested Field

Source

[
	{
		"name": "select",
		"type": "select",
		"label": "Example",
		"options": {
			"store": [
				{
					"label": "Option A",
					"value": "a"
				},
				{
					"label": "Option B",
					"value": "b"
				}
			],
			"placeholder": {
				"label": "Select something",
				"nested": [
					{
						"type": "text",
						"name": "why",
						"label": "Why didn't you select anything?"
					}
				]
			}
		}
	}
]

Editable Select (deprecated)

Since Apps platform version 2, all select have set mappable (editable) to true by default.