Autocomplete Input

Tips & examples

A robust, highly searchable dropdown input supporting multi-select chips, selection checkboxes, highlighting matching search terms, and virtualization for long option lists.

When to use

User needs to select a single or multiple values from a long, searchable list of options.
Populating form fields with dynamic options fetched via query operations (e.g., list of users, products, categories).

What you need

Requires binding configuration to a parent Form via elementId and fieldPath. Options are populated either through a dynamic backend query (requiring queryName, identifier, and label fields) or through static option definitions.

Examples

Selecting a country or state from a dynamic query-based option list.
Assigning multiple tags or labels to a record using multi-selection with chips.
Quick-filtering database records by utilizing Full Text Search behaviors.

Avoid

Using for small, fixed, mutually exclusive lists of 2 to 4 options where all choices should be visible at a glance — use radio_button or toggle buttons instead to avoid unnecessary click steps.
Using for free-form, unconstrained text entry where users type arbitrary strings rather than selecting from defined options — use text_input instead.
Enabling the ‘Can Be Cleared’ setting when the input field is marked non-nullable (nullable = false), as non-nullable inputs cannot resolve to an unselected empty/null state.
Disabling ‘Virtualized List’ when sourcing massive query result datasets (e.g. over 500 items), which can cause browser rendering lag and DOM performance degradation.
Attempting to configure form Data Source bindings before placing a parent default_form component on the page canvas layout.
Setting more than one option source. Exactly one of a view reference, a static option list, or a connector operation may be configured.
Combining the multi-select checkbox display with the repeated-value setting. The configuration allows only one of the two.

Properties

Editor properties

Configure these in the Application Designer property panel. Group headings mirror the editor where possible. Data Source is where the element gets its rows or field binding (a view/query, a connector operation, or a parent form field). References appear only for view-backed sources and map foreign-key ID columns to readable labels from another view.

Data Source

Element IDrequiredNumber or TextInside `dataSource`: Another element on the page whose data backs this field.
Default: none
Field PathrequiredList of Text or NumberInside `dataSource`: Path into the source element’s data (property segments).
Default: none

Options Source

Optionsrequiredundefined: Switches between ‘query’ mode (dynamically fetched database items) and ‘static’ mode (manually configured array lists).
Default: []
View NamerequiredTextInside `reference`: Database view that supplies rows or form data.
Default: none
Column NamerequiredTextInside `reference`: The unique key from the queried object to save as the selected value.
Default: none
Label FieldrequiredTextInside `connector`: The display text key shown to the user in the dropdown options list.
Default: none

Input

DisabledoptionalYes / no or Custom expression (yes/no): When true, the control cannot be edited.
Example false
Default: none

Advanced

Is ClearableoptionalYes / no: Adds an ‘X’ icon button to wipe out the current selection. Only available when the field’s data schema is nullable.
Default: none
Full Text SearchoptionalYes / no: Implements fuzzy, full-text filtering rules across option labels instead of standard prefix matches.
Default: true
First Option SelectedoptionalYes / no: If true, automatically selects the first available list option when no initial value exists.
Default: none
Autosuggest HighlightoptionalYes / no: Visually highlights matching text segments within option labels as the user types their search query.
Default: none
Virtualized ListoptionalYes / no: Enables virtualized item rendering. Improves performance drastically when lists contain hundreds of options.
Default: none
Options List SortedoptionalYes / no: Sorts dropdown options alphabetically before rendering.
Default: true

Multi Selection

Is MultioptionalYes / no

Allows users to select more than one option from the dropdown menu simultaneously.

Default: none

With CheckboxoptionalOne of: false

Adds visually interactive selection checkboxes next to options inside the dropdown menu.

Choices

false

Default: none

Allow Same ValueoptionalYes / no

Allows the same option to be selected multiple times inside a multi-selection list.

Default: none

SizeoptionalOne of: small, medium

Sets the scale size of the selected values displayed in the input field.

Choices

small — Compact height to fit multiple options with minimal vertical footprint.
medium — Standard visual height matching normal text inputs.

Default: none

Chip VariantoptionalOne of: default, outlined

Visual design system styles applied to selection badges.

Choices

default — Filled background container badges.
outlined — Bordered background container badges with clean white insides.

Default: none

Inside reference: (reference)

Column LabelrequiredText: Configuration for column Label.
Default: none

Inside connector: (connector)

Connector IDrequiredText: Installed connector that provides external data or actions.
Default: none
InputoptionalKey-value map: Configuration for input.
Default: none
Operation KeyrequiredText: Connector operation invoked by this element or action.
Default: none
Value FieldrequiredText: Configuration for value Field.
Default: none

Sizing

Default size when dropped on a page: 1 × 1.

Translatable labels

label — Visible title header associated with the autocomplete field.

Accessibility

Meets ARIA combobox pattern expectations; updates state via keyboard and supports screen reader focus guidelines.

Up/Down Arrows to focus list items.
Enter to select an option.
Backspace to remove selected chips.

Expressions

Values you can read in expressions

Other parts of your app can read live values from this element in custom expressions:

elements.customerPicker.<property>

value Varies by configuration The current value. elements.customerPicker.value

When The stored key of the chosen option — the value you filter another element by.

value full type ↕

string | number | boolean | null

searchInputValue string The current search text. elements.customerPicker.searchInputValue

options Array<object> The available options. elements.customerPicker.options

loadingOptions boolean True while the selectable options are being loaded. elements.customerPicker.loadingOptions

optionsError string Error message if the selectable options could not be loaded. elements.customerPicker.optionsError

errors any Field-level validation errors after submit or blur. elements.customerPicker.errors

touched boolean Map of fields the user has interacted with. elements.customerPicker.touched

valueObject object The full selected option record, not just its stored value. elements.customerPicker.valueObject.country

When The whole selected record rather than just its key, so you can show a second column from the same row without a further lookup.

rawOptions any The option records exactly as returned by the data source. elements.customerPicker.rawOptions

rawValueObject null The current raw value object value of this element. elements.customerPicker.rawValueObject

disabled boolean True while the control is locked and cannot be edited. elements.customerPicker.disabled

To use one of these, open the property you want to drive on the other element, switch it to expression mode in the Expression Editor, and enter:

1
elements.customerPicker.value

Replace customerPicker with this element’s unique id. Select the element in Application Designer and copy the id chip at the top of the right-hand property panel.

Composition

Where you can place it

Drag this element into one of these containers:

Actions you can point at this element

Add these from an Action Button, Call Button, or a Form’s success actions, and set Element Id to this element:

reset_input — Clears the current selection and the typed search text, returning the input to its empty state.

Sample configuration

Minimal example — required fields only ↕

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "config": {
    "reference": {
      "columnName": "columnName",
      "columnLabel": "columnLabel",
      "viewName": "contacts"
    },
    "connector": {
      "connectorId": "my_connector",
      "operationKey": "list_items",
      "valueField": "valueField",
      "labelField": "labelField",
      "input": {
        "exampleKey": "@@expression:'value'"
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "config": {
    "dataSource": {
      "elementId": "myElement",
      "fieldPath": [
        "fieldPath"
      ]
    },
    "disabled": false,
    "nullable": false,
    "reference": {
      "columnName": "columnName",
      "columnLabel": "columnLabel",
      "viewName": "contacts"
    },
    "connector": {
      "connectorId": "my_connector",
      "operationKey": "list_items",
      "valueField": "valueField",
      "labelField": "labelField",
      "input": {
        "exampleKey": "@@expression:'value'"
      }
    },
    "allowSameValue": false,
    "withCheckbox": "false",
    "isMulti": false,
    "isClearable": false,
    "filter": "@@expression:'value'",
    "fullTextSearch": false,
    "fetchDelay": 0,
    "autosuggestHighlight": false,
    "virtualizedList": false,
    "firstOptionSelected": false,
    "optionsListSorted": false,
    "size": "small",
    "chipVariant": "default"
  }
}

Ready-made setups

Dynamic Query Multi-Select with Checkboxes ↕

Connecting an autocomplete dropdown to a query datasource with multi-select active, using checkboxes and compact chip tags.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "config": {
    "dataSource": {
      "elementId": "<parentFormId>",
      "fieldPath": [
        "<fieldCollectionName>"
      ]
    },
    "optionsSource": {
      "optionsMode": "query",
      "queryName": "getUsersList",
      "identifierName": "id",
      "labelField": "displayName"
    },
    "advanced": {
      "fullTextSearch": true,
      "autosuggestHighlight": true,
      "virtualizedList": true
    },
    "multiSelection": {
      "multiSelectionEnabled": true,
      "withCheckbox": true,
      "chipSize": "small",
      "chipVariant": "outlined"
    }
  }
}

Notes

Description

The autocomplete is a normal text input enhanced by a panel of suggested options.

config

property	type	description	required
`reference`	`{columnName: string, columnLabel: string, viewName: string}`	The object defines the way of dynamic options displaying.	✔️ *if no static options
`disabled`	`boolean`	If `true`, the input will be disabled.
`isMulti`	`boolean`	If `true`, `value` must be an array and the menu will support multiple selections.
`isClearable`	`boolean`	By default is set to `true`. If `false`, the input can’t be cleared.
`allowSameValue`	`boolean`	If `true`, the option in multi select can be selected several times. Will work only if `isMulti` is set to `true`. Also, `withCheckbox` can’t be used with `allowSameValue` - checkboxes won’t be shown.
`filter`	`{combinator: “AND”	“OR”, filters: array*}`	The filter object. Options will be filtered by the filter params initially.
`options`	`[{value: number	string, label: string}]`	The array of static options. Each option in the array should be an object that contains: `value` - the option value, `label` - the option label.
`fullTextSearch`	`boolean`	Enable the full text search.
`fetchDelay`	`number`	The number of milliseconds before new options will be fetched if options are not static. Used for better performance during input changing. Set to `1000` by default.
`autosuggestHighlight`	`boolean`	If `true`, the text in auto-suggested options will be highlighted.
`virtualizedList`	`boolean`	If `true`, select options will be displayed as a virtualized list. Fast search within 10,000 options. In this case, if options are not static, a maximum of 1000 options will be fetched.
`withCheckbox`	`boolean`	If `true`, select options will be displayed with checkboxes. `isMulti` should be set to `true` and `allowSameValue` to `false` or not defined.
`variant`	`“default”	“outlined”`	The input variant. Usually, it set by the default theme.
`size`	`“small”	“medium”`	The size of the autocomplete. `"medium"` by default.
`chipVariant`	`“default”	“outlined”`	The chip variant. `isMulti` should be set to `true`.

i18n

name	description	required
label	Text displayed as input label
placeholder	Text displayed as input placeholder
loadingOptions	Text displayed while options are loading

note:

array* - Array<FixedFilterGroup | FixedFilterRule | null>.

1
type FixedFilterGroupCombinator = "AND" | "OR";

1
2
3
4
interface FixedFilterGroup {
  combinator: FixedFilterGroupCombinator;
  filters: Array<FixedFilterGroup | FixedFilterRule | null>;
}

1
2
3
4
5
interface FixedFilterRule {
  field: string;
  operator: string;
  value: any;
}