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.
• Data-driven options: Populates the option list directly from a data array using data, valueField, and labelField — the most efficient approach for large lists.

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>

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

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

For large or externally-loaded datasets, use the data prop to supply the option list directly. This is more efficient than using Option children or Items because the option list is derived in JavaScript and only re-evaluated when the data reference changes, not on every unrelated state update in the same form:

<App>
  <variable name="options" value="{[
    { value: 'opt1', label: 'first' },
    { value: 'opt2', label: 'second' },
    { value: 'opt3', label: 'third' }
  ]}" />
  <Select data="{options}" />
</App>

<App>
  <variable name="options" value="{[
    { value: 'opt1', label: 'first' },
    { value: 'opt2', label: 'second' },
    { value: 'opt3', label: 'third' }
  ]}" />
  <Select data="{options}" />
</App>

If your data uses different field names, set valueField and labelField accordingly:

<App>
  <variable name="countries" value="{[
    { code: 'us', name: 'United States' },
    { code: 'ca', name: 'Canada' },
    { code: 'gb', name: 'United Kingdom' }
  ]}" />
  <Select data="{countries}" valueField="code" labelField="name" />
</App>

<App>
  <variable name="countries" value="{[
    { code: 'us', name: 'United States' },
    { code: 'ca', name: 'Canada' },
    { code: 'gb', name: 'United Kingdom' }
  ]}" />
  <Select data="{countries}" valueField="code" labelField="name" />
</App>

Context variables available during execution:

• $group: Group name when using groupBy (available in group header templates)
• $item: Represents the current option's data (label and value properties)
• $itemContext: Provides the removeItem() method for multi-select scenarios

Behaviors

This component supports the following behaviors:

Properties

autoFocus

default: false

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

clearable

default: false

This property enables a clear button that allows the user to clear the selected value(s).

data

The data array to populate the option list from. When provided, Option children are not needed — the component builds options from this array using valueField and labelField. This is the most efficient approach for large lists because the options are derived in JavaScript and re-evaluated only when the data reference changes, not on every unrelated state update.

Provide an array of objects to populate the option list. When data is set, Option children are not required. Each item in the array is mapped to an option using valueField (default: "value") and labelField (default: "label").

<App>
  <variable name="options" value="{[
    { value: 'opt1', label: 'first' },
    { value: 'opt2', label: 'second' },
    { value: 'opt3', label: 'third' }
  ]}" />
  <Select data="{options}" />
</App>

<App>
  <variable name="options" value="{[
    { value: 'opt1', label: 'first' },
    { value: 'opt2', label: 'second' },
    { value: 'opt3', label: 'third' }
  ]}" />
  <Select data="{options}" />
</App>

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>

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

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

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

groupBy

This property sets which attribute should be used to group the available options. No grouping is done if omitted. Use it with the category attribute on Options to define groups. If no options belong to a group, that group will not be shown.

<App>
  <Select groupBy="category" placeholder="Select a product">
    <Option value="1" label="Apple" category="Fruit" />
    <Option value="2" label="Banana" category="Fruit" />
    <Option value="3" label="Other" />
    <Option value="4" label="Misc" />
    <Option value="5" label="Carrot" category="Vegetable" />
  </Select>
</App>

<App>
  <Select groupBy="category" placeholder="Select a product">
    <Option value="1" label="Apple" category="Fruit" />
    <Option value="2" label="Banana" category="Fruit" />
    <Option value="3" label="Other" />
    <Option value="4" label="Misc" />
    <Option value="5" label="Carrot" category="Vegetable" />
  </Select>
</App>

groupHeaderTemplate

Enables the customization of how option groups are displayed in the dropdown. You can use the $group context variable to access the group name.

<App>
  <Select groupBy="type" placeholder="Select a product">
    <property name="groupHeaderTemplate">
      <H3>{$group}</H3>
    </property>
    <Items items="{[
      { id: 1, name: 'MacBook Pro', type: 'Apple' },
      { id: 2, name: 'iPad Air', type: 'Apple' },
      { id: 3, name: 'XPS', type: 'Dell' },
      { id: 4, name: 'Tab', type: 'Samsung' }
    ]}">
      <Option value="{$item.id}" label="{$item.name}" type="{$item.type}" />
    </Items>
  </Select>
</App>

<App>
  <Select groupBy="type" placeholder="Select a product">
    <property name="groupHeaderTemplate">
      <H3>{$group}</H3>
    </property>
    <Items items="{[
      { id: 1, name: 'MacBook Pro', type: 'Apple' },
      { id: 2, name: 'iPad Air', type: 'Apple' },
      { id: 3, name: 'XPS', type: 'Dell' },
      { id: 4, name: 'Tab', type: 'Samsung' }
    ]}">
      <Option value="{$item.id}" label="{$item.name}" type="{$item.type}" />
    </Items>
  </Select>
</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>

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

labelField

default: "label"

The property name of each data item to use as the option label when data is provided. Defaults to "label".

Specifies which property of each data item to use as the option's display label. Only relevant when data is provided. Defaults to "label".

See the valueField example above for usage.

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>

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

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

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

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

scrollIndicators

default: true

This property controls whether scroll indicator arrows are displayed at the top and bottom of the dropdown list when the content overflows.

searchable

default: false

This property enables the search functionality in the dropdown list.

ungroupedHeaderTemplate

Enables the customization of how the ungrouped options header is displayed in the dropdown. If not provided, ungrouped options will not have a header.

<App>
  <Select groupBy="category" placeholder="Select a product">
    <property name="ungroupedHeaderTemplate">
      <H3>Other Items</H3>
    </property>
    <Option value="1" label="Apple" category="Fruit" />
    <Option value="2" label="Banana" category="Fruit" />
    <Option value="3" label="Other" />
    <Option value="4" label="Misc" />
    <Option value="5" label="Carrot" category="Vegetable" />
  </Select>
</App>

<App>
  <Select groupBy="category" placeholder="Select a product">
    <property name="ungroupedHeaderTemplate">
      <H3>Other Items</H3>
    </property>
    <Option value="1" label="Apple" category="Fruit" />
    <Option value="2" label="Banana" category="Fruit" />
    <Option value="3" label="Other" />
    <Option value="4" label="Misc" />
    <Option value="5" label="Carrot" category="Vegetable" />
  </Select>
</App>

validationIconError

Icon to display for error state when concise validation summary is enabled.

validationIconSuccess

Icon to display for valid state when concise validation summary is enabled.

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>

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

valueField

default: "value"

The property name of each data item to use as the option value when data is provided. Defaults to "value".

Specifies which property of each data item to use as the option's value. Only relevant when data is provided. Defaults to "value".

<App>
  <variable name="countries" value="{[
    { code: 'us', name: 'United States' },
    { code: 'ca', name: 'Canada' },
    { code: 'gb', name: 'United Kingdom' }
  ]}" />
  <Select data="{countries}" valueField="code" labelField="name" />
</App>

<App>
  <variable name="countries" value="{[
    { code: 'us', name: 'United States' },
    { code: 'ca', name: 'Canada' },
    { code: 'gb', name: 'United Kingdom' }
  ]}" />
  <Select data="{countries}" valueField="code" labelField="name" />
</App>

valueTemplate

This property allows replacing the default template to display a selected value. It works in both single-select and multi-select modes (multiSelect is true).

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>

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

variant

default: "default"

Controls the visual border treatment. outlined matches the border color of an outlined Button, so that a Select can be visually composed next to one. Only the border color (and its hover/focus states) is affected; padding, background, and typography are unchanged.

Available values:

Use variant="outlined" when you want the Select to share its border color with an outlined Button placed alongside. Both components resolve to the same borderColor-outlined theme token, so the borders stay in sync even when the theme changes.

<App>
  <HStack>
    <Select variant="outlined">
      <Option value="all" label="All customers"/>
      <Option value="active" label="Active"/>
    </Select>
    <Button icon="plus" label="New Customer" variant="outlined" />
  </HStack>
</App>

<App>
  <HStack>
    <Select variant="outlined">
      <Option value="all" label="All customers"/>
      <Option value="active" label="Active"/>
    </Select>
    <Button icon="plus" label="New Customer" variant="outlined" />
  </HStack>
</App>

The outlined variant only rebinds the border color (and its hover/focus states); padding, background, and typography are unchanged. Validation states (error / warning / valid) take precedence over the variant.

verboseValidationFeedback

Enables a concise validation summary (icon) in input components.

Events

didChange

This event is triggered when value of Select has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

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

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

Signature: gotFocus(): void

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

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

Signature: lostFocus(): void

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>

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

<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

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• clearButton: The button to clear the selected value(s).
• item: Each option item within the Select component.
• menu: The dropdown menu within the Select component.

Styling

Theme Variables