Autocomplete

Searchable combobox input with keyboard navigation (arrow keys + Enter), a filtered dropdown, and optional free‑text entry. It can use static options or load options dynamically from queries. Suitable when users must search or filter from many options (10 +). For fewer than 10 fixed options, use a Dropdown instead.

Use Cases

• Country/state selection from lookup table (200 + items)
• Customer or contact search from database
• Product search within a category
• User/employee lookup by name
• Category selection from large taxonomy
• Any entity lookup where the user needs to search and select

Properties

name

Field name for form submission. Type: string. Required.

label

Label displayed above the input. Type: string.

placeholder

Placeholder text when empty. Type: string. Default: Search...

optionsQuery

Load autocomplete options dynamically from a list query (e.g., Customers, Products, Countries). Takes precedence over static options array. Type: object.

Tip: Use optionsQuery for entity lookups (Customers, Products, Countries) where options come from a database. Do not use for tiny fixed lists – use static options instead.

Sub‑properties:

• query – Name of list query defined in root.props.queries. Type: string. Required.
• valueField – Field from query records to use as option value. Type: string. Required.
• labelField – Field from query records to use as option display label. Type: string. Required.

options

Static array of options (fallback if optionsQuery not defined). Each option has a value and label. Type: array.

required

Whether selection is required. Type: boolean. Default: false.

allowFreeText

When true, accepts values not in options list. When false, only predefined values are valid. Type: boolean. Default: false.

binding

Query‑centric data binding to store selected value. SEPARATE from optionsQuery – binding stores the SELECTED VALUE, optionsQuery loads the OPTION LIST. Type: object.

Sub‑properties:

• query – Name of query to bind to. Type: string. Required.
• field – Field name to store selected value. Type: string. Required.
• isReadOnly – Indicates if the bound field is read‑only. Type: boolean. Default: false.

customCss

Custom CSS styles. Type: string.

Best Practices

• Use Autocomplete when there are 10 + options – Dropdown is better for fewer.
• Use optionsQuery for lookup tables (Customers, Products, Countries) – loads from database dynamically.
• Use static options array ONLY for small fixed lists that don’t come from a database.
• CRITICAL: binding (value storage) is INDEPENDENT from optionsQuery (option list loading).
• Write a descriptive placeholder: ‘Search customers…’ not just ‘Search’.
• Set allowFreeText: true when users might need to enter values not in the list.
• Set allowFreeText: false when only predefined values are valid (e.g., countries).

Common Mistakes

Using Autocomplete with only 3-5 options

Why it's a problem: For few options, a Dropdown is simpler and more intuitive.

Fix: Use Dropdown for under 10 options. Use Autocomplete for 10 + options where search is valuable.

Hardcoding 200 + options in static array instead of using optionsQuery

Why it's a problem: Bloats the page data and options can’t update when database changes.

Fix: Create a list query for the lookup table and use optionsQuery to reference it.