Learning jQuery

The jQuery Autocomplete plugin got a successor recently, the jQuery UI Autocomplete. In this guide we'll look at the old plugin API step-by-step, and how to migrate to the new API.

At first it may look like the new plugin supports barely any of the old options. We'll see how all the old options can be implemented using the three new options and the six events.

The old plugin had two arguments: data or url, and options. Lets start with that data-or-url argument. With the new autocomplete plugin, you'll just pass the data or url to the source option.

So, with the old plugin you'd have this code:

[js]$("input").autocomplete(["a", "b", "c"]);[/js]

And that becomes, easy enough:

[js]$("input").autocomplete({ source: ["a", "b", "c"] });[/js]

The same applies if you provided a URL as the first argument, although there is a difference between the two plugins for remote data. The old plugin expected a special format with pipes to separate values and newlines to separate rows. That is gone for good, the Autocomplete widget now works with JSON by default. The simplest form is the same as in the example above, an array of string values.

Instead of an array of strings, the widget also accepts an array of objects, with at least a label or value property, or both, in addition to whatever else you need. More on that can be found in the documentation and various demos, eg. the Custom Data demo shows how to use custom properties and even display them.

Lets look through the rest of the options for the old plugin, and what to do with them for the new plugin:

• autoFill: Gone with no immediate replacement available, for good reasons: The default behaviour when selecting items via keyboard now puts the focussed value into the input, like the Firefox Awesomebar does it. It's not the same as what the autoFill option did, but there should be no need to recreate that effect.
• cacheLength: There is no built-in caching support anymore, but it's really easy to implement your own, as shown by the Remote with caching demo.
• delay: Still exists with the same behaviour, but the default is always 300 milliseconds.
• extraParams: Extra params and all other Ajax related options can be customized by using a callback for the source option. Use $.ajax to send the actual request, with the response callback argument passed to source as the success callback for the $.ajax call. The Remote JSONP datasource demo has an example for that.
• formatItem, formatMatch, formatResult, highlight: All gone, instead use the source option to either provide the formatted data from your serverside, or implement a custom source to do special formatting. The combobox demo shows how to do that, with a more extensive explanation of that demo right on this site.
• matchCase, matchContains, matchSubset: All gone, too. The builtin matcher for local data will do a case-insensitive match-contains, everything else has to be implemented on the serverside or using the source option. The combobox linked just above also has an example for that.
• max: Gone; if your server sends too many items, pass a function for the source option that calls $.ajax and truncates or filters the resulting list.
• minChars: Still present, but was renamed to minLength. Behaves just the same, even the default is still the same, with minLength: 1.
• multiple, multipleSeperator: Not built-in anymore, but easy to recreate. There are two demos for this, once with local data, once with remote data.
• mustMatch: Gone, but easy to implement with the select event. Once more, the combobox provides an example for that.
• scroll, scrollHeight: These option are gone, but the underlying Menu widget actually has support for scrolling. If you have enough items and specify a height via CSS, the menu will scroll.
• selectFirst: Similar to autoFill (at the top of this list), this option is gone and has now immediate replacement, nor a need for one. The behaviour for selecting values is solid enough to make this option redundant.
• width: Gone and not required anymore. The menu will automatically be as wide as the input it completes, or wider, as the content requires. And you can always restrict with width using CSS.

And thats about it. If you're still looking for a particular replacement, take a look at the various events available, and study the use of the source-option within the various demos. If you still have a question, post on the Using jQuery UI forum. If you spot some mistake or see something that can be improved in this article, please let us know in the comments.