stable 1.1.0

Autocomplete

A combobox with built-in fetch: type, and the menu fills from your endpoint — grouped results, icons, sublabels, loading and empty states. Link ng_autocomplete.js.

Wrap an input and an empty ng-autocomplete-menu in a ng-autocomplete root with data-ng-autocomplete and a data-url. The script debounces typing, aborts stale requests (AbortController), validates the JSON and renders via textContent — never innerHTML. The menu opens in the top layer with keyboard navigation and ARIA roles.

Live demo

Backed by a demo endpoint with European cities, grouped by country. Type “mi”, “ro” or “par”:

autocomplete.html
<div class="ng-field">
    <label class="ng-label">City</label>
    <div class="ng-autocomplete" data-ng-autocomplete
         data-url="/en/api/docs/cities"
         data-min-chars="2"
         data-debounce="250"
         data-limit="8">
        <input type="text" class="ng-input" placeholder="Type at least 2 letters — try “mi” or “ro”…">
        <div class="ng-autocomplete-menu" role="listbox" hidden></div>
    </div>
</div>

Match highlight

data-highlight="1" wraps the matching letters in a <mark>.

autocomplete.html
<div class="ng-field">
    <label class="ng-label">City (match highlighted)</label>
    <div class="ng-autocomplete" data-ng-autocomplete
         data-url="/en/api/docs/cities"
         data-highlight="1">
        <input type="text" class="ng-input" placeholder="Try “bar”…">
        <div class="ng-autocomplete-menu" role="listbox" hidden></div>
    </div>
</div>

Backend contract

The endpoint receives ?q=…&limit=… (names configurable) and must answer:

response.json
{
    "results": [
        {
            "value":    "RM",              // required · string
            "label":    "Roma",            // required · string
            "sublabel": "Lazio · Italia",  // optional · second line
            "icon":     "ph-map-pin",      // optional · Phosphor class
            "group":    "Italia",          // optional · group heading
            "disabled": false,             // optional
            "meta":     { }                 // optional · free payload
        }
    ],
    "total": 124,                          // optional
    "query": "rom"                         // optional · echo
}

Invalid payloads (non-array results, items without string value/label) are rejected and surface the error state.

Attributes

data-urlEndpoint URL — required.
data-min-charsMin chars before searching (default 2).
data-debounceDebounce in ms (default 250).
data-limitResults to request (default 10).
data-query-param / data-limit-paramQuery-string names (default q / limit).
data-methodGET (default) or POST.
data-headersExtra request headers as a JSON object.
data-highlight1 → wrap the match in <mark>.
data-allow-free1 → Enter accepts free text (no item selected).

Events & API

Events are dispatched on the root:

ng:autocomplete:open ng:autocomplete:close ng:autocomplete:select ng:autocomplete:results ng:autocomplete:error

Per-instance API on root.__ngAutocomplete:

app.js
const ac = document.querySelector('.ng-autocomplete').__ngAutocomplete;

ac.open();  ac.close();
ac.search('rom');           // programmatic search
ac.select(item);  ac.clear();
ac.getValue();              // selected value
ac.setValue('RM', 'Roma');  // set without searching

Anatomy

ng-autocomplete data-ng-autocomplete ng-autocomplete-menu ng-autocomplete-item ng-autocomplete-body ng-autocomplete-label ng-autocomplete-sublabel ng-autocomplete-icon ng-autocomplete-group ng-autocomplete-status

States

is-open is-active is-loading is-error

Reference

Generated from the component source (_ng_autocomplete.scss · ng_autocomplete.js).

Component info

Nameautocomplete
Typecss+js
Version1.1.0
Statusstable
CSS/assets/css/components/_ng_autocomplete.scss
JS/assets/js/ng_autocomplete.js

Classes

.ng-autocomplete .ng-autocomplete-body .ng-autocomplete-control .ng-autocomplete-group .ng-autocomplete-icon .ng-autocomplete-item .ng-autocomplete-label .ng-autocomplete-menu .ng-autocomplete-status .ng-autocomplete-sublabel .ng-chip .ng-dropdown-menu .ng-input .ng-spinner

Tokens

--ng-ac-group-color --ng-ac-icon-color --ng-ac-item-active-bg --ng-ac-item-gap --ng-ac-item-hover-bg --ng-ac-item-padding-x --ng-ac-item-padding-y --ng-ac-menu-bg --ng-ac-menu-border --ng-ac-menu-max-h --ng-ac-menu-radius --ng-ac-menu-shadow --ng-ac-sublabel-color --ng-ac-z --ng-spinner-border-width

Events

ng:autocomplete:add ng:autocomplete:close ng:autocomplete:error ng:autocomplete:open ng:autocomplete:remove ng:autocomplete:results ng:autocomplete:select