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.

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.

[
	{
		"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.

[
	{
		"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.

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

["breakfast","dinner"]

Multiple Choice with Validation

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

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
	{
		"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.

[
   {
       "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.

[
	{
		"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.

PreviousPort NextText

Last updated 1 month ago