AutoComplete

AutoComplete is a searchable dropdown input that allows users to type and filter through options, with support for single or multiple selections. Unlike a basic Select, it provides type-ahead functionality and can allow users to create new options.

Key features:

Type-ahead filtering: Users can type to narrow down options in real-time
Multi-select support: Set multi="true" to allow selecting multiple items
Custom option creation: Enable creatable="true" to let users add new options
Rich customization: Use optionTemplate to create complex option layouts

Using AutoComplete

<App>
  <AutoComplete>
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" enabled="false" />
    <Option value="3" label="Diana Prince" />
  </AutoComplete>
</App>

Example: Using AutoComplete

<App>
  <AutoComplete>
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" enabled="false" />
    <Option value="3" label="Diana Prince" />
  </AutoComplete>
</App>

Context variables available during execution:

$item: This context value represents an item when you define an option item template. Use $item.value and $item.label to refer to the value and label of the particular option.

Properties

`autoFocus` (default: false)

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

`creatable` (default: false)

This property allows the user to create new items that are not present in the list of options.

`dropdownHeight`

This property sets the height of the dropdown list.

`emptyListTemplate`

This property defines the template to display when the list of options is empty.

<App>
  <AutoComplete>
    <property name="emptyListTemplate">
      <Text>No options found</Text>
    </property>
  </AutoComplete>
</App>

Example: emptyListTemplate

<App>
  <AutoComplete>
    <property name="emptyListTemplate">
      <Text>No options found</Text>
    </property>
  </AutoComplete>
</App>

`enabled` (default: true)

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

`initiallyOpen` (default: false)

This property determines whether the dropdown list is open when the component is first rendered.

`initialValue`

This property sets the component's initial value.

`maxLength`

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

`multi` (default: false)

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

    <App>
      <AutoComplete multi="true">
        <Option value="1" label="Bruce Wayne" />
        <Option value="2" label="Clark Kent" />
        <Option value="3" label="Diana Prince" />
        <Option value="4" label="Barry Allen" />
        <Option value="5" label="Hal Jordan" />
      </AutoComplete>
    </App>

Example: multi

    <App>
      <AutoComplete multi="true">
        <Option value="1" label="Bruce Wayne" />
        <Option value="2" label="Clark Kent" />
        <Option value="3" label="Diana Prince" />
        <Option value="4" label="Barry Allen" />
        <Option value="5" label="Hal Jordan" />
      </AutoComplete>
    </App>

`optionTemplate`

This property enables the customization of list items. To access the attributes of a list item use the $item context variable.

<App>
  <AutoComplete multi="true">
    <property name="optionTemplate">
      <Text textAlign="center" color="red">{$item.label}</Text>
    </property>
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" />
    <Option value="3" label="Diana Prince" />
  </AutoComplete>
</App>

Example: optionTemplate

<App>
  <AutoComplete multi="true">
    <property name="optionTemplate">
      <Text textAlign="center" color="red">{$item.label}</Text>
    </property>
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" />
    <Option value="3" label="Diana Prince" />
  </AutoComplete>
</App>

`placeholder`

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

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

`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

Events

`didChange`

This event is triggered when value of AutoComplete has changed.

`gotFocus`

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

`itemCreated`

This event is triggered when a new item is created by the user (if creatable is enabled).

Add a few new items not in the options list. The following markup will display them:

<App var.newItems="{[]}">
  <AutoComplete
    id="autoComplete"
    creatable="true"
    onItemCreated="item => newItems.push(item)">
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" />
  </AutoComplete>
  <Text testId="text">
    New items: {newItems.join(", ")}
  </Text>
</App>

Example: itemCreated

<App var.newItems="{[]}">
  <AutoComplete
    id="autoComplete"
    creatable="true"
    onItemCreated="item => newItems.push(item)">
    <Option value="1" label="Bruce Wayne" />
    <Option value="2" label="Clark Kent" />
  </AutoComplete>
  <Text testId="text">
    New items: {newItems.join(", ")}
  </Text>
</App>

`lostFocus`

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

Exposed Methods

`focus`

This method focuses the AutoComplete component.

Signature: focus()

`setValue`

This API allows you to set the value of the component. If the value is not valid, the component will not update its internal state.

Signature: setValue(value: any)

value: The value to set.

`value`

This API allows you to get or set the value of the component. If no value is set, it will retrieve undefined.

Signature: get value(): any

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-AutoComplete--disabled	none	none
backgroundColor-AutoComplete-badge	$color-primary-500	$color-primary-500
backgroundColor-AutoComplete-badge	$color-primary-500	$color-primary-500
backgroundColor-AutoComplete-badge--active	$color-primary-500	$color-primary-500
backgroundColor-AutoComplete-badge--active	$color-primary-500	$color-primary-500
backgroundColor-AutoComplete-badge--hover	$color-primary-400	$color-primary-400
backgroundColor-AutoComplete-badge--hover	$color-primary-400	$color-primary-400
backgroundColor-AutoComplete-default	none	none
backgroundColor-AutoComplete-default--hover	none	none
backgroundColor-AutoComplete-error	none	none
backgroundColor-AutoComplete-error--hover	none	none
backgroundColor-AutoComplete-success	none	none
backgroundColor-AutoComplete-success--hover	none	none
backgroundColor-AutoComplete-warning	none	none
backgroundColor-AutoComplete-warning--hover	none	none
backgroundColor-item-AutoComplete	$backgroundColor-dropdown-item	$backgroundColor-dropdown-item
backgroundColor-item-AutoComplete--active	$backgroundColor-dropdown-item--active	$backgroundColor-dropdown-item--active
backgroundColor-item-AutoComplete--hover	$backgroundColor-dropdown-item--hover	$backgroundColor-dropdown-item--hover
backgroundColor-menu-AutoComplete	$color-surface-raised	$color-surface-raised
backgroundColor-menu-AutoComplete	$color-surface-raised	$color-surface-raised
border-AutoComplete	none	none
borderBottom-AutoComplete	none	none
borderBottomColor-AutoComplete	none	none
borderBottomStyle-AutoComplete	none	none
borderBottomWidth-AutoComplete	none	none
borderColor-AutoComplete	none	none
borderColor-AutoComplete--disabled	initial	initial
borderColor-AutoComplete--disabled	initial	initial
borderColor-AutoComplete-default	none	none
borderColor-AutoComplete-default--hover	none	none
borderColor-AutoComplete-error	none	none
borderColor-AutoComplete-error--hover	none	none
borderColor-AutoComplete-success	none	none
borderColor-AutoComplete-success--hover	none	none
borderColor-AutoComplete-warning	none	none
borderColor-AutoComplete-warning--hover	none	none
borderColor-menu-AutoComplete	$borderColor	$borderColor
borderColor-menu-AutoComplete	$borderColor	$borderColor
borderEndEndRadius-AutoComplete	none	none
borderEndStartRadius-AutoComplete	none	none
borderHorizontal-AutoComplete	none	none
borderHorizontalColor-AutoComplete	none	none
borderHorizontalStyle-AutoComplete	none	none
borderHorizontalWidth-AutoComplete	none	none
borderLeft-AutoComplete	none	none
color-AutoComplete	none	none
borderLeftStyle-AutoComplete	none	none
borderLeftWidth-AutoComplete	none	none
borderRadius-AutoComplete-badge	$borderRadius	$borderRadius
borderRadius-AutoComplete-default	none	none
borderRadius-AutoComplete-error	none	none
borderRadius-AutoComplete-success	none	none
borderRadius-AutoComplete-warning	none	none
borderRadius-menu-AutoComplete	$borderRadius	$borderRadius
borderRadius-menu-AutoComplete	$borderRadius	$borderRadius
borderRight-AutoComplete	none	none
color-AutoComplete	none	none
borderRightStyle-AutoComplete	none	none
borderRightWidth-AutoComplete	none	none
borderStartEndRadius-AutoComplete	none	none
borderStartStartRadius-AutoComplete	none	none
borderStyle-AutoComplete	none	none
borderStyle-AutoComplete-default	none	none
borderStyle-AutoComplete-error	none	none
borderStyle-AutoComplete-success	none	none
borderStyle-AutoComplete-warning	none	none
borderTop-AutoComplete	none	none
borderTopColor-AutoComplete	none	none
borderTopStyle-AutoComplete	none	none
borderTopWidth-AutoComplete	none	none
borderHorizontal-AutoComplete	none	none
borderVerticalColor-AutoComplete	none	none
borderVerticalStyle-AutoComplete	none	none
borderVerticalWidth-AutoComplete	none	none
borderWidth-AutoComplete	none	none
borderWidth-AutoComplete-default	none	none
borderWidth-AutoComplete-error	none	none
borderWidth-AutoComplete-success	none	none
borderWidth-AutoComplete-warning	none	none
borderWidth-menu-AutoComplete	1px	1px
borderWidth-menu-AutoComplete	1px	1px
boxShadow-AutoComplete-default	none	none
boxShadow-AutoComplete-default--hover	none	none
boxShadow-AutoComplete-error	none	none
boxShadow-AutoComplete-error--hover	none	none
boxShadow-AutoComplete-success	none	none
boxShadow-AutoComplete-success--hover	none	none
boxShadow-AutoComplete-warning	none	none
boxShadow-AutoComplete-warning--hover	none	none
boxShadow-menu-AutoComplete	$boxShadow-md	$boxShadow-md
boxShadow-menu-AutoComplete	$boxShadow-md	$boxShadow-md
fontSize-AutoComplete-badge	$fontSize-sm	$fontSize-sm
fontSize-AutoComplete-badge	$fontSize-sm	$fontSize-sm
fontSize-AutoComplete-default	none	none
fontSize-AutoComplete-error	none	none
fontSize-AutoComplete-success	none	none
fontSize-AutoComplete-warning	none	none
fontSize-placeholder-AutoComplete-default	none	none
fontSize-placeholder-AutoComplete-error	none	none
fontSize-placeholder-AutoComplete-success	none	none
fontSize-placeholder-AutoComplete-warning	none	none
opacity-AutoComplete--disabled	0.5	0.5
opacity-text-item-AutoComplete--disabled	0.5	0.5
outlineColor-AutoComplete--focus	none	none
outlineOffset-AutoComplete--focus	none	none
outlineStyle-AutoComplete--focus	none	none
outlineWidth-AutoComplete--focus	none	none
padding-AutoComplete	none	none
padding-item-AutoComplete	none	none
paddingBottom-AutoComplete	none	none
paddingBottom-item-AutoComplete	none	none
paddingHorizontal-AutoComplete	$space-2	$space-2
paddingHorizontal-AutoComplete-badge	$space-2_5	$space-2_5
paddingHorizontal-item-AutoComplete	$space-2	$space-2
paddingLeft-AutoComplete	none	none
paddingLeft-item-AutoComplete	none	none
paddingRight-AutoComplete	none	none
paddingRight-item-AutoComplete	none	none
paddingTop-AutoComplete	none	none
paddingTop-item-AutoComplete	none	none
paddingVertical-AutoComplete	$space-2	$space-2
paddingVertical-AutoComplete-badge	$space-0_5	$space-0_5
paddingVertical-item-AutoComplete	$space-2	$space-2
textColor-AutoComplete--disabled	none	none
textColor-AutoComplete-badge	$const-color-surface-50	$const-color-surface-50
textColor-AutoComplete-badge	$const-color-surface-50	$const-color-surface-50
textColor-AutoComplete-badge--active	none	none
textColor-AutoComplete-badge--hover	none	none
textColor-AutoComplete-default	none	none
textColor-AutoComplete-default--hover	none	none
textColor-AutoComplete-error	none	none
textColor-AutoComplete-error--hover	none	none
textColor-AutoComplete-success	none	none
textColor-AutoComplete-success--hover	none	none
textColor-AutoComplete-warning	none	none
textColor-AutoComplete-warning--hover	none	none
textColor-item-AutoComplete--disabled	$color-surface-200	$color-surface-200
textColor-placeholder-AutoComplete	none	none
textColor-placeholder-AutoComplete-default	none	none
textColor-placeholder-AutoComplete-error	none	none
textColor-placeholder-AutoComplete-success	none	none
textColor-placeholder-AutoComplete-warning	none	none

AutoComplete

Using AutoComplete

Properties

autoFocus (default: false)

creatable (default: false)

dropdownHeight

emptyListTemplate

enabled (default: true)

initiallyOpen (default: false)

initialValue

maxLength

multi (default: false)

optionTemplate

placeholder

readOnly (default: false)

required (default: false)

validationStatus (default: "none")