I’ve been answering jQueryUI autocomplete questions on StackOverflow now for over two and a half years and I’ve noticed that there are a few things that are always coming up. This post will attempt to clear up those sources of confusion.
jQuery Autocomplete vs. jQueryUI autocomplete
jQuery autocomplete is jQueryUI autocomplete’s predecessor. Despite the multiple messages and disclaimers on the legacy plugin’s page, there is still confusion about the documentation, functionality, and status of this plugin. For some reason, some folks do not notice the following message on Jörn Zaefferer’s documentation page for the plugin:
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, but won’t be updated anymore.
The link to the migration guide explains how to migrate your old code using the original, deprecated plugin with the new one provided by jQueryUI.
What format does my data need to be in?
Another source of confusion is exactly what format does the widget’s data source need to take? This is easy to see after viewing a few examples and reading the overview tab on the documentation page.
To summarize, the data that you send to the widget needs to be:
- An array of strings
- An array of objects. Each object should have a either a
valueproperty, or both.
An important point on #2 is that the object can contain other properties (besides
value). This comes in handy when doing custom things with data.
I am using a server-side source and my data isn’t being filtered!
When you use a server-side resource, you are responsible for doing the filtering. Usually this occurs by building up a database query based on the term that the user searched for.
If you don’t want to filter your data with server-side code (which I highly recommend), you could retrieve all of the possible results via AJAX and then let the widget do the filtering. Here’s an example using StackOverflow’s API:
This may not be ideal depending on the size of the data you are processing. You may want to handle the filtering on the server rather than bogging the browser down with filtering through thousands of results.
I’m using a server-side resource that isn’t returning data in the format that autocomplete is expecting. What should I do?
You can supply a callback function to the
sourceparameter of autocomplete. This allows you to use virtually any source as long as you format it correctly before passing it to the
responsefunction that autocomplete uses to populate the results. Here’s another example using the StackOverflow API:
The key here is to use
$.mapto transform the results into the format that the widget expects (described above).
I want to implement tagging functionality. How can I go about that?
This is the most complex of the 5, but it is doable. Check out the multiple values demo for one way to do this.
I’ve demonstrated a more complex Google-plus like functionality in the answer to this question. Here’s an updated fiddle using the 2.1 version of the API.
This demo is also useful because it shows a custom display of each tag including the count. Type @j to see tags starting with “j”.
jQueryUI autocomplete’s API may look simple at first glance, but this is a very extensible and capable plugin. Most people’s questions revolve around the
source parameter for the plugin. Remember to look at your AJAX requests in Firebug or similar just to make sure the data you’re supplying to the widget is what you expect.