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>

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

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.

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>

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

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

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

Events

didChange

This event is triggered when value of AutoComplete has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

gotFocus

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

Signature: gotFocus(): void

itemCreated

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

Signature: (item: string) => void

• item: The newly created item value.

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>

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

Signature: lostFocus(): void

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.

verboseValidationFeedback

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

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