Autocomplete Migration Guide

read 29 comments

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:

JavaScript:
  1. $("input").autocomplete(["a", "b", "c"]);

And that becomes, easy enough:

JavaScript:
  1. $("input").autocomplete({
  2.   source: ["a", "b", "c"]
  3. });

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.

comment feed

29 comments

  1. I recently moved over to the UI autocomplete (although right now that's all I'm using UI for) and the only problem I had was a z-index issue with the Cycle based slide show below the search box on some pages. The parent of the search box needed to have a higher z-index than any of the children in the slide show. Our slide shows have 3 elements so the autocomplete div needed to be at least 4 higher than the z-index for the parent of the slide show elements.

    All that functionality was built in and it was easy enough to fix, just 2 new lines of CSS.

  2. The new width behavior is pretty cool; otherwise, I still like the old plugin better. No built-in caching? How lame is that! I know, I know, it's not hard to implement, but come on: why not have it built in!

  3. Because caching isn't a common enough usecase, often data has to be fresh, never cached. Because caching requires local matching, witch can't always implement the same matching strategy that the server implements (see the Remote JSONP datasource demo, a search for "Köln" matches Cologne, how am I supposed to implement that in a generic clientside cache?). Because cache invalidation is hard. All that is easy enough to implement on-the-fly, as the demos show, and that way you can customize it based on the needs of your application.

    And just because its not included, yet, doesn't mean we won't add it later, when we have more usecase, more data, more algorithms, whatever will come help us to provide a simple and powerful solution.

  4. Paul

    Jörn,

    Are you going to continue to support your autocomplete? I'd rather not migrate if I can avoid it!

    Thanks for all your efforts!

  5. Nope, I won't. Thats the point of this post, also explained on my blog.

  6. I was used your plugin in two projects for a while and want to thank you for a great job. And of course, thanks a lot for migration guide.

  7. Peter

    How do I allow scrolling in the menu?

  8. Peter

    How do I turn the parts of the menu that match the term bold?

  9. Jörn:
    Given that a callback can be the data source now. Is there any reason a person should avoid searching a local data set and then querying the server only if there are no matches locally?

  10. @Aaron: Nope, you can do that.

  11. Chewby

    Thank you very much for all that information on the component. I am trying since this morning to add a srcoll the list of items without much sucked.

    I do not know where you have to add the property of the height in the css ...
    I try a lot of thing but its not working!

    Have you an example to get the scroll ?

    Cordially

    PS: I do not know your site is really complementary, I find much more information and detail really well.

    • Chewby

      I must be too tired from my last evening I had not read well.
      But on IE there are problems when you scroll !
      The scroll disappears!

  12. Kye

    Hi, noticed that the drop-down list is now working in the new ui autocomplete for IE 6 with the screen reader JAWS. May I ask what change was required to get it working? I hope to replicate the same change for the original autocomplete. Thanks.

  13. vespadj

    I will not upgrade to the ui.autocomplete.

    1. ui.autocomplete not work anymore with url that response "simply text" in rows. why?

    2. I like very much in the old , the zebra effect (ac_odd) and the 'strong' text in the result list. How can I obtain it with the new?

  14. You can implement the old parsing behaviour using the source option, I've created an example here: http://jsbin.com/axuzu4/5/edit

    The highlighting can be implemented that way, too. The Combobox post from this site explains the code.

  15. Alex Aulbach

    I upgraded last week. I go thoroughly through this list and made all changes. 2 Problems remaining:

    1. I formerly used result() as explained and showed in http://docs.jquery.com/Plugins/Autocomplete#Search_Page_Replacement
    I get now the error "result is not a function". A rewrite of result() failed. Does rewrite no longer exists?

    2. The source:-ajax-request works and returns JSON-results, but they aren't showed. When I write the JSON-results into the source-definition it also doesn't work. With pure arrays it works. Doesn't it work with JSON-Objects?

  16. @Alex: The forum is a much better place to answer those questions. Please post there, along with a testpage. Thanks.

  17. Sebastian

    HI there, I have a question about the selectFirst option - you say it is gone with no need for replacement, but I disagree.

    I have a strong case for an instance where I need to be able to input something - say the word 'Widget'. If present in the source list I have, 'Widget' contains all kind of other information such as ID's that I need to have access to when the user blurs out of the autocomplete.

    However if I type out 'Widget' in the autocomplete and just tab out without selecting the matching item 'Widget' from the dropdown list, this item is never selected and I don't get that extra data. This is bad behavior, at least for my needs, and there's got to be a way to address this issue. Do you have any solutions or workarounds?

  18. @Sebastian: Scott wrote an extension for selectFirst. That should do the trick.

    • Andrew

      I completely agree with Sebastian, please do not underestimate the power of this feature. As far as I can see the extension does not behave the same as the original. It should "highlight" the option and not "select" it until the user presses TAB or ENTER, as per the default behaviour on your original demo page.

      I love your old extension Jörn but won't be migrating until this is resolved.

      Does anyone have any alternative solutions? Thanks.

  19. Joachim Habib

    Hello guys,

    I was using old autocomplete plugin for few weeks and found it pretty cool with a very well documented API.
    I discovered yesterday it is not supported anymore, so I started to have a look at the new API and what a surprised, it's pretty empty. I read your migration guide (thanks a lot btw) and discovered a lot of old functionnalities are gone but can easily rebuild (by my own). But why do you have remove all old functionnalities and make all user to build it by their own ? An example with "multiple" option, now 25 lines of JS strictly identical will be written in each JQuery UI based project. Imagine if you want to change something in your own code in 2 years (I saw lots of page showing how to rebuild old functionnalities by overwritting function started by "_", I guess this is "private" function of the plugin), everybody will have to update code.
    I fully understand you have to simplify API in order to put the plugin in set of JQuery UI ones, but did you plan to have a look at old functionnalities one by one and try to integrate it ?

    Again thanks for this migration guide and effort you've done.

    Joachim

  20. Example of what to use instead of matchContains:false would be nice :)

  21. Kerr

    Jörn - Thanks for your continued efforts! I've used your autocomplete plugin for a couple years now, and have been watching the jQuery UI based plugin with great interest. Today I implemented the new plugin across all of my sites, and while it took some adjustment, I see the wisdom in all the changes that were made. On the whole, my autocomplete calls are much more terse while still carrying the same functionality. I also like that I can simply apply CSS styles for the different states.

  22. MaT

    Is it possible, somehow, to have both versions active at the same time? They are both called by .autocomplete... I want to change to newer version in my application, but it is very complex, I will have to change a lot and I think that doing it progressively will be easier for me...

    Should I change the function name in js source?

  23. Yeah, in this case changing the source is the best option. Once you're done with the migration you'd remove the renamed one anyway.

  24. Daniel

    hi,
    How do i limit the number of results displayed in the suggestion.I used max:20 but its not working . And i am passing Array which contains json data as the source to the autocomplete and by default it does contains operation , i want startswith , How do i achieve this. Can somebody help me out.
    Thanks

  25. Dylan

    A quick question. Is there a number of records limit for autocomplete?

    I am displaying some data from the database and IE8, Firefox, Safari and Chrome all work fine with 110,00 records - but for some reason I am getting Out of memory error in IE6 and IE7. If I limit number of records to 50,000 it works in IE6 and IE7.

    Any ideas what's going on?

    BTW I am using the old version, does anyone knows if upgrading to new version will fix this?

    Thanks!

3 Pings

  1. [...] This plugin is deprecated and not developed anymore. Its successor is part of jQuery UI, and this migration guide explains how to get from this plugin to the new one. This page will remain as it is for reference, [...]

Sorry, but comments for this entry are now closed.