Adds autocomplete / autosuggest dropdowns to text input fields.
The only runtime dependency is jQuery 3.0 or newer. TypeScript types are bundled.
The UMD bundle (dist/jquery.autocomplete.js) is ~13 KB minified;
an ESM build (dist/jquery.autocomplete.esm.js) is also published for modern bundlers.
npm install devbridge-autocompleteOr load via a <script> tag — the UMD bundle registers $.fn.autocomplete
(and $.fn.devbridgeAutocomplete) on the global jQuery.
Version 2.0 drops support for jQuery 1.x / 2.x and IE-era browsers.
The plugin API and option names are unchanged — every existing call site
continues to work — but the peer dependency is now jquery >=3.0 and the
build targets evergreen browsers (ES2020). If you cannot upgrade jQuery,
stay on the 1.5.x release line.
$(selector).autocomplete(options);options is an object literal. All recognized fields are listed in the
tables below.
| Setting | Default | Description |
|---|---|---|
minChars | 1 | Minimum characters typed before suggestions are fetched |
delimiter | optional | string or RegExp that splits the input value; the last segment becomes the query. Useful for comma-separated value lists |
noCache | false | If true, suggestion results are not cached |
preventBadQueries | true | If true, suppresses future Ajax requests for any query that starts with a prefix that previously returned no results. E.g. once Jam returns nothing, Jamai will not fire |
triggerSelectOnValidInput | true | If true, onSelect fires automatically when the input exactly matches a suggestion |
autoSelectFirst | false | If true, the first item is selected when suggestions appear |
preserveInput | false | If true, the input value does not change while navigating suggestions with arrow keys |
tabDisabled | false | If true, pressing Tab keeps the cursor in the input field instead of selecting the highlighted suggestion |
showNoSuggestionNotice | false | If true, displays a label when no suggestions match |
noSuggestionNotice | "No results" | Text, HTML string, Element, or jQuery object used as the no-match label |
groupBy | optional | Property on suggestion.data to group results by |
formatResult | optional | function (suggestion, currentValue) — custom HTML for a single suggestion entry |
formatGroup | optional | function (suggestion, category) — custom HTML for a group header |
beforeRender | optional | function (container, suggestions) — called before the dropdown is shown; mutate the DOM here if needed |
onInvalidateSelection | optional | function () — fires when the input changes after a selection was made. this is the input element |
maxHeight | 300 | Maximum dropdown height in pixels |
width | "auto" | Dropdown width. Number (px), "auto" (matches the input), or "flex" (grows to widest suggestion) |
zIndex | 9999 | z-index of the dropdown container |
orientation | "bottom" | "top", "bottom", or "auto". "auto" picks the side with more room |
appendTo | document.body | jQuery object, selector, or HTMLElement. The target needs position: absolute or position: relative |
forceFixPosition | false | Auto-positioning only runs when the dropdown is appended to <body>. Set this to true to force positioning in other parents |
containerClass | "autocomplete-suggestions" | CSS class on the dropdown container. Override if you need a different style hook |
| Callback | Signature | Description |
|---|---|---|
onSearchStart | function (params) | Fires before each lookup. Return false to cancel. this is the input element |
onSearchComplete | function (query, suggestions) | Fires after each lookup resolves. this is the input element |
onSearchError | function (query, jqXHR, textStatus, errorThrown) | Fires if the Ajax request fails. this is the input element |
onSelect | function (suggestion) | Fires when the user picks a suggestion. this is the input element |
onHint | function (hint) | Fires when the inline hint changes. this is the input element |
onHide | function (container) | Fires before the dropdown is hidden |
transformResult | function (response, originalQuery) | Normalizes the raw server response into { suggestions: [...] }. Default: JSON.parse on a string response |
| Setting | Default | Description |
|---|---|---|
lookup | optional | Either an array of suggestions or a callback function (query, done). Arrays may be strings or { value, data } objects |
lookupFilter | optional | function (suggestion, query, queryLowerCase) — filter predicate. Default is a case-insensitive substring match |
lookupLimit | unlimited | Maximum number of local matches to display |
A suggestion is an object of the form { value: string, data: any }. data
is passed through untouched to formatResult, onSelect, and the grouping
key resolver.
| Setting | Default | Description |
|---|---|---|
serviceUrl | required for Ajax | A URL string, or function (query) returning a URL string |
type | "GET" | HTTP method |
dataType | "text" | "text", "json", or "jsonp". jsonp is recognized by jQuery's Ajax layer |
paramName | "query" | Name of the request parameter holding the query |
params | optional | Extra parameters merged into every request |
ignoreParams | false | If true, suppresses the query-string data payload. Useful when serviceUrl is a callback that builds the entire URL itself |
deferRequestBy | 0 | Milliseconds to wait before firing the request, so fast typists don't trigger one per keystroke |
ajaxSettings | optional | Extra jQuery Ajax settings merged into the request |
Defaults are accessible (and writable) at $.Autocomplete.defaults.
| Method | Description |
|---|---|
setOptions(options) | Updates any option(s) at any time |
clear() | Clears the suggestion cache and the current suggestions |
clearCache() | Clears only the suggestion cache |
disable() | Deactivates autocomplete |
enable() | Reactivates autocomplete after disable() |
hide() | Hides the dropdown |
dispose() | Destroys the instance, detaches all event handlers, and removes the dropdown container |
There are two ways to call a method. Pass the method name as a string, followed by any arguments:
$('#autocomplete').autocomplete('disable');$('#autocomplete').autocomplete('setOptions',options);Or grab the Autocomplete instance by calling autocomplete() with no
arguments, then invoke the method on it:
$('#autocomplete').autocomplete().disable();$('#autocomplete').autocomplete().setOptions(options);HTML:
<inputtype="text" name="country" id="autocomplete" />Ajax lookup:
$('#autocomplete').autocomplete({serviceUrl: '/autocomplete/countries',onSelect: function(suggestion){console.log(`Picked: ${suggestion.value}, ${suggestion.data}`);},});Local lookup (no Ajax):
constcountries=[{value: 'Andorra',data: 'AD'},// ...{value: 'Zimbabwe',data: 'ZZ'},];$('#autocomplete').autocomplete({lookup: countries,onSelect: function(suggestion){console.log(`Picked: ${suggestion.value}, ${suggestion.data}`);},});Custom lookup function — do whatever you want, then call done with the
result:
$('#autocomplete').autocomplete({lookup: function(query,done){done({suggestions: [{value: 'United Arab Emirates',data: 'AE'},{value: 'United Kingdom',data: 'UK'},{value: 'United States',data: 'US'},],});},onSelect: function(suggestion){console.log(`Picked: ${suggestion.value}, ${suggestion.data}`);},});The generated dropdown markup looks like this — style any of the classes to taste:
<divclass="autocomplete-suggestions"><divclass="autocomplete-group"><strong>NHL</strong></div><divclass="autocomplete-suggestion autocomplete-selected">...</div><divclass="autocomplete-suggestion">...</div><divclass="autocomplete-suggestion">...</div></div>Minimal CSS to get started:
.autocomplete-suggestions { border:1px solid #999; background:#fff; overflow: auto; }
.autocomplete-suggestion { padding:2px5px; white-space: nowrap; overflow: hidden; cursor: pointer; }
.autocomplete-selected { background:#f0f0f0; }
.autocomplete-suggestionsstrong { font-weight: normal; color:#3399ff; }
.autocomplete-group { padding:2px5px; }
.autocomplete-groupstrong { display: block; border-bottom:1px solid #000; }cursor: pointer on .autocomplete-suggestion is required for tap-to-select
to fire on mobile Safari — see issue #542.
The server must respond with JSON in this shape:
{
"suggestions": [
{ "value": "United Arab Emirates", "data": "AE" },
{ "value": "United Kingdom", "data": "UK" },
{ "value": "United States", "data": "US" }
]
}data may be any value or object — it is passed unchanged to
formatResult, onSelect, and the grouping key resolver. If you have no
data, a plain string array is also accepted:
{ "suggestions": ["United Arab Emirates", "United Kingdom", "United States"] }The optional query field on the response was required up to version
1.2.5; newer versions ignore it.
If your service expects a differently named query parameter or returns a
non-standard payload, use paramName and transformResult:
$('#autocomplete').autocomplete({paramName: 'searchString',transformResult: function(response){return{suggestions: response.myData.map((item)=>({value: item.valueField,data: item.dataField,})),};},});Set groupBy to a property name on suggestion.data to render group
headers. For example, groupBy: 'category' with this data:
[{value: 'Chicago Blackhawks',data: {category: 'NHL'}},{value: 'Chicago Bulls',data: {category: 'NBA'}},];renders two groups, NHL and NBA.
jQuery UI also defines a plugin named autocomplete. When both are loaded,
this plugin yields and registers only $.fn.devbridgeAutocomplete, so use
the alias:
$('.autocomplete').devbridgeAutocomplete({ ... });To report a vulnerability, please do not open a public GitHub issue. Use GitHub's Private Vulnerability Reporting form on this repository — it routes the report directly to the maintainers. Full policy and supported-version table: SECURITY.md.
Ajax Autocomplete for jQuery is freely distributable under the terms of an MIT-style license. The copyright and permission notices must be included with any copy or substantial portion of the software.
Tomas Kirda / @tkirda