FormWidgets / Selection / Autocomplete

Autocomplete

fw-autocomplete

A type-ahead search widget with matching text highlighting, label/value pair support, remote API fetching, and complete keyboard navigation. Stores an ID value separately from the display label.

View Examples

Usage

Local Array Source

JavaScript
FormWidgets.init('#country', 'Autocomplete', {
    source: [
        { label: 'United Kingdom', value: 'GB' },
        { label: 'United States', value: 'US' },
        { label: 'Germany', value: 'DE' }
    ]
});

Remote API Source

JavaScript
FormWidgets.init('#station', 'Autocomplete', {
    source: 'https://api.example.com/stations',
    minLength: 2,
    delay: 300
});

With Value Display (showValue)

JavaScript
FormWidgets.init('#station', 'Autocomplete', {
    source: 'https://api.example.com/stations',
    showValue: true,
    valueFormat: '[{value}]'
    // Dropdown shows: "London Paddington [1]"
    // Field stores: "London Paddington" (label only)
    // data-value stores: "1" (ID only)
});

HTML with Data Attributes

HTML
<input type="text" class="fw-autocomplete"
       data-source="/api/stations"
       data-min-length="2"
       data-show-value="true"
       data-value-format="[{value}]">

Options

OptionTypeDefaultDescription
sourcearray / string[]Data source. Either an array of items, or a URL string for remote fetching. See Source Formats below.
minLengthnumber1Minimum characters to type before the search is triggered.
maxResultsnumber10Maximum number of items shown in the dropdown.
delaynumber300Debounce delay in milliseconds for remote sources. Prevents excessive API calls while the user is typing.
labelFieldstring'label'Field name for the display text. Supports 'label', 'l', or a custom field name.
valueFieldstring'value'Field name for the stored value/ID. Supports 'value', 'r', or a custom field name.
showValuebooleanfalseWhen true, shows the value alongside the label in the dropdown (e.g. London [1]). The field itself only stores the label.
valueFormatstring'[{value}]'Template for displaying the value in the dropdown when showValue is true. Use {value} as the placeholder.
iconstring'search'Name of the SVG icon to use from the internal icon set.
requiredbooleanfalseMarks the field as required.

Source Formats

The source option accepts several data formats:

JavaScript
// Simple string array
source: ['Apple', 'Banana', 'Cherry']

// Label/Value objects (standard)
source: [
    { label: 'London Paddington', value: '1' },
    { label: 'Manchester Piccadilly', value: '2' }
]

// Pair format (short-hand)
source: [
    { l: 'High Priority', r: '1' },
    { l: 'Medium Priority', r: '2' },
    { l: 'Low Priority', r: '3' }
]

// Custom field names
source: [{ name: 'Item 1', id: '1' }]
// + options: { labelField: 'name', valueField: 'id' }

// Remote URL — GET request with ?q=searchTerm
source: 'https://api.example.com/search'

Getting Values

JavaScript
// Get the display label (from input.value)
const label = document.getElementById('station').value;
// e.g. 'London Paddington'

// Get the stored ID/value (from data-value attribute)
const id = document.getElementById('station').getAttribute('data-value');
// e.g. '1'

// Use widget instance methods
const widget = FormWidgets.instances.get(document.getElementById('station'));
const value = widget.getValue();   // Returns stored ID
const label2 = widget.getLabel();  // Returns display label

showValue does NOT affect stored values

When showValue: true, the dropdown shows London Paddington [1] but the field stores only London Paddington, and data-value stores only 1. The format string is only visual.

Pre-filled Values

If the page loads with an existing ID in data-value, the widget automatically fetches and displays the corresponding label from the remote source.

HTML
<!-- Pre-filled with ID 5 —— widget auto-loads the label -->
<input id="station" data-value="5">
JavaScript
FormWidgets.init('#station', 'Autocomplete', {
    source: 'https://api.example.com/stations'
    // Automatically calls GET /stations/5 to retrieve the label
});

Keyboard Navigation

↓Move to next item in the dropdown list
↑Move to previous item in the dropdown list
EnterSelect the highlighted item and close the dropdown
EscClose the dropdown without selecting
TabClose the dropdown and move focus to the next field

Features

Text Highlighting

Matching search text is automatically bolded in the dropdown.

Label/Value Pairs

Stores an ID value separately from the display label.

Remote Source

Fetch results from any URL with automatic debouncing.

Chevron Animation

Chevron icon rotates 180° when the dropdown opens.