Select

Provides a dropdown with a list of options to choose from.

The component provides context values with which you can access some internal properties:

• $item: This property represents the value of an item in the dropdown list.
• $itemContext: This property provides a removeItem method to delete the particular value from the selection.

Using Select

The component accepts Option components as children defining a particular option's label-value pair. Option requires a value property and while also having a label that is displayed in the list. If the label is not specified value is shown.

<App>
  <Select>
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

You can use Select with dynamic options:

<App>
  <Select>
    <Items data="{['one', 'two', 'three']}" >
      <Option value="{$itemIndex}" label="{$item}" />
    </Items> 
  </Select>
</App>  

Properties

autoFocus (default: false)

If this property is set to true, the component gets the focus automatically when displayed.

dropdownHeight

This property sets the height of the dropdown list.

<App>
  <Select dropdownHeight="180px">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
    <!-- Omitted -->
    <Option value="opt11" label="eleventh"/>
    <Option value="opt12" label="twelfth"/>
  </Select>
</App>

emptyListTemplate

This optional property provides the ability to customize what is displayed when the list of options is empty.

Click on the second field to see the custom empty list indicator.

<App>
  <VStack>
    <Text value="Default:" />
    <Select />
  </VStack>
  <VStack>
    <Text value="Custom:" />
    <Select>
      <property name="emptyListTemplate">
        <Text variant="strong" value="Nothing to see here!" />
      </property>
    </Select>
  </VStack>
</App>

enabled (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

<App>
  <Select enabled="false" />
</App>

inProgress

This property indicates whether the component is in progress. It can be used to show a loading message.

inProgressNotificationMessage

This property indicates the message to display when the component is in progress.

initialValue

This property sets the component's initial value.

<App>
  <Select initialValue="opt3">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

label

This property sets the label of the component.

labelBreak (default: false)

This boolean value indicates if the Select labels can be split into multiple lines if it would overflow the available label width.

labelPosition (default: "top")

Places the label at the given position of the component.

Available values:

labelWidth

This property sets the width of the Select.

maxLength

This property sets the maximum length of the input it accepts.

multiSelect (default: false)

The true value of the property indicates if the user can select multiple items.

<App>
  <Select multiSelect="true" dropdownHeight="180px" >
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
    <!-- Omitted -->
    <Option value="opt11" label="eleventh"/>
    <Option value="opt12" label="twelfth"/>
  </Select>
</App>

optionLabelTemplate

This property allows replacing the default template to display an option in the dropdown list.

In the template definition, you can use the $item context property to access the particular item's label and value.

<App>
  <Select initialValue="{0}" placeholder="Select..." searchable>
    <property name="optionLabelTemplate">
      <HStack 
        paddingHorizontal="$padding-tight" 
        border="2px dotted $color-primary-500">
        <Text>{$item.label}</Text>
      </HStack>
    </property>
    <Option value="{0}" label="zero"/>
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

optionTemplate

This property allows replacing the default template to display an option in the dropdown list.

<App>
  <Select>
    <property name="optionTemplate">
      <HStack verticalAlignment="center" gap="$space-0_5">
        <Icon name="info" />
        <Text value="{$item.label}" variant="strong" />
      </HStack>
    </property>
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

placeholder

A placeholder text that is visible in the input field when its empty.

<App>
  <Select placeholder="Please select an item">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

readOnly (default: false)

Set this property to true to disallow changing the component value.

required

Set this property to true to indicate it must have a value before submitting the containing form.

searchable

This property enables the search functionality in the dropdown list.

validationStatus (default: "none")

This property allows you to set the validation status of the input component.

Available values:

<App>
  <Select />
  <Select validationStatus="valid" />
  <Select validationStatus="warning" />
  <Select validationStatus="error" />
</App>

valueTemplate

This property allows replacing the default template to display a selected value when multiple selections (multiSelect is true) are enabled.

In the template definition, you can use the $item context property to access the particular item's label and value. The $itemContext property provides a removeItem method to delete a value from the current selection.

<App>
  <Select initialValue="{0}" placeholder="Select..." multiSelect>
    <property name="valueTemplate">
      <HStack 
        paddingLeft="$padding-tight" 
        border="2px dotted $color-primary-500"              
        verticalAlignment="center">
        <Text>{$item.label}</Text>
        <Button 
          variant="ghost"
          icon="close" 
          size="xs" 
          onClick="$itemContext.removeItem()"/>
      </HStack>
    </property>
    <Option value="{0}" label="zero"/>
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>  

Events

didChange

This event is triggered when value of Select has changed.

<App>
  <variable name="newValue" value="" />
  <Text value="{newValue}" />
  <Select onDidChange="(newItem) => newValue = newItem">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

gotFocus

This event is triggered when the Select has received the focus.

<App>
  <variable name="isFocused" value="{false}" />
  <Text value="Input control is focused: {isFocused}" />
  <Select
    onGotFocus="isFocused = true"
    onLostFocus="isFocused = false">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

lostFocus

This event is triggered when the Select has lost the focus.

Exposed Methods

focus

This method sets the focus on the Select.

<App>
  <Button label="Focus Input" onClick="inputControl.focus()" />
  <Select id="inputControl">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
</App>

reset

This method resets the component to its initial value, or clears the selection if no initial value was provided.

setValue

You can use this method to set the component's current value programmatically (true: checked, false: unchecked).

<App>
  <Select id="inputControl">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
  </Select>
  <HStack>
    <Button
      label="Select 2nd Item"
      onClick="inputControl.setValue('opt2')" />
    <Button
      label="Remove Selection"
      onClick="inputControl.setValue('')" />
  </HStack>
</App>

value

You can query the component's value. If no value is set, it will retrieve undefined.

Styling

The Select component uses these theme variables:

• minHeight-Select

These variables have 4 variants depending on the validationStatus denoted by |status|. If the status segment is omitted, the style will be applied to all statuses.

• borderRadius-Select-|status|

• fontSize-Select-|status|

• textColor-placeholder-Select-|status|

• borderWidth-Select-|status|

• outlineWidth-Select-|status|--focus

• outlineColor-Select-|status|--focus

• outlineStyle-Select-|status|--focus

• outlineOffset-Select-|status|--focus

"borderRadius-Select-default": "10px",
"textColor-placeholder-Select-error": "crimson"

In addition to the validation statuses, the variables below are associated with styles for hover and disabled interaction states denoted by |interact| in their signature:

• borderColor-Select-|status|--|interact|
• backgroundColor-Select-|status|--|interact|
• boxShadow-Select-|status|--|interact|
• textColor-Select-|status|--|interact|

"backgroundColor-Select-default--disabled": "gray",
"textColor-Select-error--active": "lightcoral"

Theme variables to set the dropdown menu styles:

• backgroundColor-menu-Select
• boxShadow-menu-Select
• borderRadius-menu-Select
• textColor-indicator-Select

Theme variables to set the selection styles in a dropdown menu:

• textColor-value-Select
• backgroundColor-value-Select

Theme variables to set the styles of an unselected item:

• backgroundColor-item-Select--hover
• backgroundColor-item-Select--active
• textColor-item-Select--disabled

Example

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "borderRadius-Select": "30px",
    "textColor-placeholder-Select": "red",
    "borderWidth-Select": "4px"
  }
}

To style all input controls not just this component, use Input instead of the Select segment:

borderColor-Input: "#0033FF"

Input affects the following controls:

• Checkbox
• NumberBox
• RadioGroupOption
• Switch
• TextArea
• TextBox
• MultiSelect
• MultiCombobox

See custom themes for styling details.

Theme Variables