Using

Plug-in extends jQuery namespace with autocomplete(options) function.

Applying is usual for jQuery

$('input,textarea').autocomplete({get:get_function,...});

Each text element may be affected only once, non text elements not affected at all.

Options

options is object with next fields:

get -- function called for synchronous getting suggestions. The function must accepts one argument: string for suggest searching, and returns array of objects, where each object has id, value and info (optional) fields (suggest object).

ajax_get -- function called for asynchronous getting suggestions. The function must accepts two arguments: string for suggest searching and continuation function for return suggestion results (array of suggest objects).

pre_callback -- function called before get or ajax_get, without arguments.

callback -- function called after choosing item from suggestions list. The function accepts one argument: suggest object.

minchars -- minimum number of characters required for auto-complete (default 3).

delay -- number of milliseconds, delay for getting started.

timeout -- number of milliseconds, timeout for close autocomplete menu.

cache -- if false, results caching disabled (default true).

height -- number of pixels of auto-complete menu height (default 150).

autowidth -- if false, menu width is like text field width (default false).

multi -- if true, multi complete enabled. Input defined by commas and caret position, like gmail auto-complete in composing (default false).

noresults -- message if there is no results.

Implementation Details

Suggestions menu is DIV element with unordered list within.

DIV.jqac-menu
  UL
    LI
      SPAN.jqac-link _value text_
      SPAN.jqac-info _info text_
    ...

Keyboard (ENTER, ESC, ARRUP, ARRDOWN) and mouse events captured.

Also used auto scrolling for suggests menu.

CSS

Here is sample CSS with comments

/* Menu DIV */
.jqac-menu{
  color: black;
  background-color: white;
  border: 1px solid #aaa;
}
/* unordered list for suggestions */
.jqac-menu ul{
  list-style: none;
  margin: 1px;
  padding: 1px;
  overflow: hidden;
}
/* SPAN "link" */
.jqac-menu .jqac-link {
  cursor: hand; cursor: pointer;
  display: block;
}
/* highlighted menu item */
.jqac-menu .jqac-highlight {
  background-color: #ddf;
}
/* warning for no results */
.jqac-menu .jqac-warning {
  font-style: italic;
}
/* loading for AJAX get */
.jqac-menu .jqac-loading {
  font-style: italic;
  text-decoration: blink;
}
/* matched sub-string */
.jqac-menu em {
    text-decoration: underline;
}
/* suggestion info */
.jqac-menu .jqs-info {
    text-align: right;
    font-style: italic;
    font-size: .75em;
    color: #666;
}

Example

<script type="text/javascript">
function get_random_suggs(v){ 
   var a=[];
   var names = ['_first','_second','_third','_forth','_fifth'];
   for(var i=0;i<names.length;i++) {
     a.push({id:i, value:v+names[i], info:"demo string #"+i, extra:"extra fields remains!" });
   }
   return a;
}
function print_sugg(obj){ 
  $('#info').html('ID: '+obj.id+'<br>VALUE: '+obj.value+'<br>EXTRA: '+obj.extra); 
}
$(document).ready(function(){
    $('input.complete').autocomplete({ get : get_random_suggs, 
                                       callback: print_sugg,
                                       multi: true});
});
</script>
<div id="info"></div>
<input class="complete" id="input" size="45"/>

onfocus Example (lazy init)

Autocomplete initialization may be performed when user focuses on text field

<div id="info"></div>
<input class="complete" id="input" size="45" onfocus="$(this).autocomplete({get:get_random_suggs,callback:print_sugg})"/>

AJAX Example

The server script look.php (LOOK(1) Unix command):

<?
exec('look '.escapeshellarg($_REQUEST['q']),$lines);
$res = array();
foreach($lines as $l){
  $res[] = "'".str_replace("'","\\'",$l)."'";
}
print '['.implode(',',$res).']';
?>

Client javascript:

/**
 * key: input for LOOK(1)
 * cont: function(res) for return of suggest results
*/ 
function get_look_suggs(key,cont){ 
   var script_name = '/path/to/look.php';
   var params = { 'q':key }
   $.get(script_name,params,
         function(obj){ 
           // obj is just array of strings
           var res = [];
           for(var i=0;i<obj.length;i++){
             res.push({ id:i , value:obj[i]});
           }
           // will build suggestions list
           cont(res); 
         },
         'json');
}
$(document).ready(function(){
    $('input.complete').autocomplete({ ajax_get : get_look_suggs });
});

IE 6 Issue

bgIframe plugin solves well known bug with zIndex of element over select combo boxes.

This plug-in supports bgiframe call for scrollable suggest list, so all you need is to load bgiframe plug-in too:

<script type="text/javascript" src="/path/to/jquery.bgiframe.js"></script>

Online Examples

More working examples.