Autocomplete Plugin for JQuery 1.3.2

(based on Autocomplete Ajax Powered for Prototype of Antonio Ramirez Cobos -myself)

Here's Version 1.0.1 of my Ajax-powered auto-complete textfield.

Due to the success of my version for Prototype and after I've finally got time to do it, I decided to create my own plugin for JQuery -which is the js framework I am using for my projects nowadays.

The functionality is exactly the same as the version for Prototype.


Examples & description

Example (JSON)


The AutoComplete class adds a pulldown menu of suggested values to a text field. The user can either click directly on a suggestion to enter it into the field, or navigate the list using the up and down arrow keys, selecting a value using the enter key. The values for the suggestion list are to provided as XML, or as JSON (by a PHP, ASP, ASPX script, or similar).

The results of the first request are cached on the client machine and are filtered as the user continues to type, to reduce the number of requests hitting the server.

In the JSON example above a callback function is passed to the AutoComplete instance. It is called when the user selects an entry, and writes the full entry info into an span object.

Example (XML)


The script requires jquery.1.3.2.js and a single javascript file to be included in the HEAD:

  • autocomplete.js

A normal text field is transformed into an AutoComplete text field dynamically by using the following code

    var options = {
		callback: function (obj) { 
			$('json_info').update('you have selected: ' + ' ' +
			obj.value + ' (' + + ')'); }

The options object contains the options for the AutoComplete instance. Note that the script variable includes the question mark (?) at the end. This is to allow other variables to be passed to the script via GET (to use POST method, you will need to modify the AJAX (-doAjaxRequest function) request and also the , for example script: "". The varname option is the name of the variable that should contain the current value of the text field, and is simpy added on to the end of the script variable when the script is called, along with the current value of the text field, giving:

The script variable can also be a function:

script: function (input) { 
		return "test.php?input="+input+"&testid="+document.getElementById('testid').value;

This allows you to build the script URL dynamically, passing variable data from somewhere else in your document (eg. from another field, as in the example above). If the script returns false, no AJAX request will be made.

The XML output from the script should have the following structure (you can modify this and its client handle via the setSuggestions function of the AutoComplete object:

	<rs id="1" info="">Foobar</rs>
	<rs id="2" info="">Foobarfly</rs>
	<rs id="3" info="">Foobarnacle</rs>

A JSON object should have the following structure:

{ results: [
	{ id: "1", value: "Foobar", info: "Cheshire" },
	{ id: "2", value: "Foobarfly", info: "Shropshire" },
	{ id: "3", value: "Foobarnacle", info: "Essex" }
] }

The AutoComplete object creates the following XHTML code, inserting as the last element in the body:

<div style="left: 347px; top: 1024px; width: 400px;" class="autosuggest" id="ac_testinput_xml">
	<div class="ac_header">
		<div class="ac_corner"></div>
		<div class="ac_bar"></div>
	<ul id="ac_ul">
			<a name="1" href="#">
			<span class="tl"> </span>
			<span class="tr"> </span>
			<span><em>W</em>aldron, Ashley<br><small>Leicestershire</small></span>
			<a name="2" href="#">
			<span class="tl"> </span>
			<span class="tr"> </span>
			<span><em>W</em>heeler, Bysshe<br><small>Lincolnshire</small></span>
	<div class="ac_footer">
		<div class="ac_corner"></div>
		<div class="ac_bar"></div>


The list can then be styled using normal CSS. Check out the CSS file.


The default timeout is set at 2500 milliseconds. After two and a half seconds of inactivity the list closes itself. However, this timeout is reset each time the user types another character. Furthermore, if the user moves the mouse pointer over the AutoComplete list, the timeout is cancelled altogether, until the mouse pointer is moved off the list.


The options object can contain the following properties:



Property Type Default Description
script String / Function - REQUIRED!
Either: A string containing the path to the script that returns the results in XML format. (eg, "myscript.php?")
Or: A function that accepts on attribute, the autosuggest field input as a string, and returns the path to the result script.
varname String "input" Name of variable passed to script holding current input.
minchars Integer 1 Length of input required before AutoSuggest is triggered.
className String "autocomplete" Value of the class name attribute added to the generated ul.
delay Integer 500 Number of milliseconds before an AutoSuggest AJAX request is fired.
timeout Integer 2500 Number of milliseconds before an AutoSuggest list closes itself.
cache Boolean true Whether or not a results list should be cached during typing.
offsety Integer -5 Vertical pixel offset from the text field.
shownoresults Boolean true Whether to display a message when no results are returned.
noresults String No results! No results message.
callback Function   A function taking one argument: an object

{id:"1", value:"Foobar", info:"Cheshire"}
json Boolean false Whether or not a results are returned in JSON format. If not, script assumes results are in XML.
maxentries Integer 25 The maximum number of entries being returned by the script. (Should correspond to the LIMIT clause in the SQL query.)
onAjaxError function null

If an Ajax request fails, this function will be called (if any). NOTE: a parameter (HTTP_STATUS) will be passed to the function, so you can display your own custom error message.


setWidth Boolean false If set to true, the dropdown list will be within the boundaries of minWidth and maxWidth options.
minWidth Integer 100 If setWidth is equal to true, then the dropdown list will be a minimum width of whatever this option specifies
maxWidth Integer 200 If setWidth is equal to true, then the dropdown list will be a maximum width of whatever this option specifies
useNotifier Boolean true true by default, this option will display icons to notify that is an autocomplete textfield and also a spinner when an AJAX call is being made to the server.