Select

Select provides a dropdown interface for choosing from a list of options, supporting both single and multiple selection modes. It offers extensive customization capabilities including search functionality, custom templates, and comprehensive form integration.

Key features:

Flexible selection modes: Single selection by default, with optional multi-select capability
Option containers: Uses Option components to define selectable items with separate values and labels
Search functionality: Optional filtering to quickly find options in large lists
Custom templates: Configurable option display, value presentation, and empty state templates
Dynamic options: Supports both static Option children and dynamic lists via Items.

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>

Example: using Select

<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>

Example: using Select with dynamic options

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

Context variables available during execution:

$item: Represents the current option's data (label and value properties)
$itemContext: Provides utility methods like removeItem() for multi-select scenarios

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. If not set, the height is determined automatically.

<App>
  <Select dropdownHeight="180px">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
    <Option value="opt4" label="fourth"/>
    <Option value="opt5" label="fifth"/>
    <Option value="opt6" label="sixth"/>
    <Option value="opt7" label="seventh"/>
    <Option value="opt8" label="eighth"/>
    <Option value="opt9" label="ninth"/>
    <Option value="opt10" label="tenth"/>
    <Option value="opt11" label="eleventh"/>
    <Option value="opt12" label="twelfth"/>
  </Select>
</App>

Example: dropdownHeight

<App>
  <Select dropdownHeight="180px">
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
    <Option value="opt4" label="fourth"/>
    <Option value="opt5" label="fifth"/>
    <Option value="opt6" label="sixth"/>
    <Option value="opt7" label="seventh"/>
    <Option value="opt8" label="eighth"/>
    <Option value="opt9" label="ninth"/>
    <Option value="opt10" label="tenth"/>
    <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>

Example: emptyListTemplate

<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>

Example: enabled

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

`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>

Example: initialValue

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

`inProgress` (default: false)

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

`inProgressNotificationMessage` (default: "")

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

`label`

This property sets the label of the component. If not set, the component will not display a label.

`labelBreak` (default: false)

This boolean value indicates whether the Select label 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:

Value	Description
`start`	The left side of the input (left-to-right) or the right side of the input (right-to-left)
`end`	The right side of the input (left-to-right) or the left side of the input (right-to-left)
`top`	The top of the input (default)
`bottom`	The bottom of the input

`labelWidth`

This property sets the width of the Select component's label. If not defined, the label's width will be determined by its content and the available space.

`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"/>
    <Option value="opt4" label="fourth"/>
    <Option value="opt5" label="fifth"/>
    <Option value="opt6" label="sixth"/>
    <Option value="opt7" label="seventh"/>
    <Option value="opt8" label="eighth"/>
    <Option value="opt9" label="ninth"/>
    <Option value="opt10" label="tenth"/>
    <Option value="opt11" label="eleventh"/>
    <Option value="opt12" label="twelfth"/>
  </Select>
</App>

Example: multiSelect

<App>
  <Select multiSelect="true" dropdownHeight="180px" >
    <Option value="opt1" label="first"/>
    <Option value="opt2" label="second"/>
    <Option value="opt3" label="third"/>
    <Option value="opt4" label="fourth"/>
    <Option value="opt5" label="fifth"/>
    <Option value="opt6" label="sixth"/>
    <Option value="opt7" label="seventh"/>
    <Option value="opt8" label="eighth"/>
    <Option value="opt9" label="ninth"/>
    <Option value="opt10" label="tenth"/>
    <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>

Example: optionLabelTemplate

<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>

Example: optionTemplate

<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` (default: "")

An optional 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>

Example: placeholder

<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` (default: false)

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

`searchable` (default: false)

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:

Value	Description
`valid`	Visual indicator for an input that is accepted
`warning`	Visual indicator for an input that produced a warning
`error`	Visual indicator for an input that produced an error

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

Example: validationStatus

<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>

Example: valueTemplate

<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="(none)" />
  <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>

Example: didChange

<App>
  <variable name="newValue" value="(none)" />
  <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>

Example: gotFocus/lostFocus

<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 focuses the Select component. You can use it to programmatically focus the component.

Signature: focus(): void

<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>

Example: focus()

<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.

Signature: reset(): void

`setValue`

This API sets the value of the Select. You can use it to programmatically change the value.

Signature: setValue(value: string | string[] | undefined): void

value: The new value to set. Can be a single value or an array of values for multi-select.

<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>

Example: setValue()

<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`

This API retrieves the current value of the Select. You can use it to get the value programmatically.

Signature: get value(): string | string[] | undefined

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-item-Select	$backgroundColor-dropdown-item	$backgroundColor-dropdown-item
backgroundColor-item-Select--active	$backgroundColor-dropdown-item--active	$backgroundColor-dropdown-item--active
backgroundColor-item-Select--hover	$backgroundColor-dropdown-item--hover	$backgroundColor-dropdown-item--hover
backgroundColor-menu-Select	$color-surface-raised	$color-surface-raised
backgroundColor-menu-Select	$color-surface-raised	$color-surface-raised
backgroundColor-Select--disabled	none	none
backgroundColor-Select-badge	$color-primary-500	$color-primary-500
backgroundColor-Select-badge	$color-primary-500	$color-primary-500
backgroundColor-Select-badge--active	$color-primary-500	$color-primary-500
backgroundColor-Select-badge--active	$color-primary-500	$color-primary-500
backgroundColor-Select-badge--hover	$color-primary-400	$color-primary-400
backgroundColor-Select-badge--hover	$color-primary-400	$color-primary-400
backgroundColor-Select-default	none	none
backgroundColor-Select-default--hover	none	none
backgroundColor-Select-error	none	none
backgroundColor-Select-error--hover	none	none
backgroundColor-Select-success	none	none
backgroundColor-Select-success--hover	none	none
backgroundColor-Select-warning	none	none
backgroundColor-Select-warning--hover	none	none
borderColor-menu-Select	$borderColor	$borderColor
borderColor-menu-Select	$borderColor	$borderColor
borderColor-Select--disabled	initial	initial
borderColor-Select--disabled	initial	initial
borderColor-Select-default	none	none
borderColor-Select-default--hover	none	none
borderColor-Select-error	none	none
borderColor-Select-error--hover	none	none
borderColor-Select-success	none	none
borderColor-Select-success--hover	none	none
borderColor-Select-warning	none	none
borderColor-Select-warning--hover	none	none
borderRadius-menu-Select	$borderRadius	$borderRadius
borderRadius-menu-Select	$borderRadius	$borderRadius
borderRadius-Select-badge	$borderRadius	$borderRadius
borderRadius-Select-default	none	none
borderRadius-Select-error	none	none
borderRadius-Select-success	none	none
borderRadius-Select-warning	none	none
borderStyle-Select-default	none	none
borderStyle-Select-error	none	none
borderStyle-Select-success	none	none
borderStyle-Select-warning	none	none
borderWidth-menu-Select	1px	1px
borderWidth-menu-Select	1px	1px
borderWidth-Select-default	none	none
borderWidth-Select-error	none	none
borderWidth-Select-success	none	none
borderWidth-Select-warning	none	none
boxShadow-menu-Select	$boxShadow-md	$boxShadow-md
boxShadow-menu-Select	$boxShadow-md	$boxShadow-md
boxShadow-Select-default	none	none
boxShadow-Select-default--hover	none	none
boxShadow-Select-error	none	none
boxShadow-Select-error--hover	none	none
boxShadow-Select-success	none	none
boxShadow-Select-success--hover	none	none
boxShadow-Select-warning	none	none
boxShadow-Select-warning--hover	none	none
fontSize-placeholder-Select-default	none	none
fontSize-placeholder-Select-error	none	none
fontSize-placeholder-Select-success	none	none
fontSize-placeholder-Select-warning	none	none
fontSize-Select	none	none
fontSize-Select-badge	$fontSize-small	$fontSize-small
fontSize-Select-badge	$fontSize-small	$fontSize-small
fontSize-Select-default	none	none
fontSize-Select-error	none	none
fontSize-Select-success	none	none
fontSize-Select-warning	none	none
opacity-Select--disabled	0.5	0.5
opacity-text-item-Select--disabled	0.5	0.5
outlineColor-Select-default--focus	none	none
outlineColor-Select-error--focus	none	none
outlineColor-Select-success--focus	none	none
outlineColor-Select-warning--focus	none	none
outlineOffset-Select-default--focus	none	none
outlineOffset-Select-error--focus	none	none
outlineOffset-Select-success--focus	none	none
outlineOffset-Select-warning--focus	none	none
outlineStyle-Select-default--focus	none	none
outlineStyle-Select-error--focus	none	none
outlineStyle-Select-success--focus	none	none
outlineStyle-Select-warning--focus	none	none
outlineWidth-Select-default--focus	none	none
outlineWidth-Select-error--focus	none	none
outlineWidth-Select-success--focus	none	none
outlineWidth-Select-warning--focus	none	none
padding-item-Select	none	none
padding-Select	none	none
paddingBottom-item-Select	none	none
paddingBottom-Select	none	none
paddingHorizontal-item-Select	$space-2	$space-2
paddingHorizontal-Select	$space-2	$space-2
paddingHorizontal-Select-badge	$space-2_5	$space-2_5
paddingLeft-item-Select	none	none
paddingLeft-Select	none	none
paddingRight-item-Select	none	none
paddingRight-Select	none	none
paddingTop-item-Select	none	none
paddingTop-Select	none	none
paddingVertical-item-Select	$space-2	$space-2
paddingVertical-Select	$space-2	$space-2
paddingVertical-Select-badge	$space-0_5	$space-0_5
textColor-indicator-Select	none	none
textColor-item-Select--disabled	$color-surface-200	$color-surface-200
textColor-placeholder-Select	none	none
textColor-placeholder-Select-default	none	none
textColor-placeholder-Select-error	none	none
textColor-placeholder-Select-success	none	none
textColor-placeholder-Select-warning	none	none
textColor-Select--disabled	none	none
textColor-Select-badge	$color-surface-50	$color-surface-50
textColor-Select-badge	$color-surface-50	$color-surface-50
textColor-Select-badge--active	none	none
textColor-Select-badge--hover	none	none
textColor-Select-default	none	none
textColor-Select-default--hover	none	none
textColor-Select-error	none	none
textColor-Select-error--hover	none	none
textColor-Select-success	none	none
textColor-Select-success--hover	none	none
textColor-Select-warning	none	none
textColor-Select-warning--hover	none	none

Select

Using Select

Properties

autoFocus (default: false)

dropdownHeight

emptyListTemplate

enabled (default: true)

initialValue

inProgress (default: false)

inProgressNotificationMessage (default: "")

label

labelBreak (default: false)

labelPosition (default: "top")

labelWidth

multiSelect (default: false)

optionLabelTemplate

optionTemplate

placeholder (default: "")

readOnly (default: false)

required (default: false)

searchable (default: false)

validationStatus (default: "none")

valueTemplate