Documentation

Plugins/Autocomplete

From jQuery JavaScript Library

Jump to: navigation, search

« Back to the jQuery Autocomplete Plugin page

Contents

[edit]

Introduction

Autocomplete an input field to enable users quickly finding and selecting some value, leveraging searching and filtering.

By giving an autocompleted field focus or entering something into it, the plugin starts searching for matching entries and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.

This can be used to enter previous selected values, eg. for tags, to complete an address, eg. enter a city name and get the zip code, or maybe enter email addresses from an addressbook.

Both local and remote data can be used: Local is good for small datasets (like an addressbook with 50 entries), remote is necessary for big datasets, like a database with hundreds or millions of entries to select from.

[edit]

Example

A simple autocompleted input, with the jQuery API Reference as data.

var data = "Core Selectors Attributes Traversing Manipulation CSS Events Effects Ajax Utilities".split(" ");
$("#example").autocomplete(data);


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
                    "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
  <link rel="stylesheet" href="http://dev.jquery.com/view/trunk/plugins/autocomplete/demo/main.css" type="text/css" />
  <link rel="stylesheet" href="http://dev.jquery.com/view/trunk/plugins/autocomplete/jquery.autocomplete.css" type="text/css" />
  <script type="text/javascript" src="http://dev.jquery.com/view/trunk/plugins/autocomplete/lib/jquery.bgiframe.min.js"></script>
  <script type="text/javascript" src="http://dev.jquery.com/view/trunk/plugins/autocomplete/lib/jquery.dimensions.js"></script>
  <script type="text/javascript" src="http://dev.jquery.com/view/trunk/plugins/autocomplete/jquery.autocomplete.js"></script>
  <script>
  $(document).ready(function(){
    var data = "Core Selectors Attributes Traversing Manipulation CSS Events Effects Ajax Utilities".split(" ");
$("#example").autocomplete(data);
  });
  </script>
  
</head>
<body>
  API Reference: <input id="example" /> (try "C" or "E")
</body>
</html>

[edit]

API Documentation

NameType
Documentation:












NameType
autocomplete( url or data, options )Returns: jQuery
Makes an input or textarea autocompleteable.
result( handler )Returns: jQuery
Handle the result of a search event.
search( )Returns: jQuery
Trigger a search event.
flushCache( )Returns: jQuery
Flush (empty) the cache of matched input's autocompleters.
setOptions( options )Returns: jQuery
Updates the options for the current autocomplete field.

[edit]

Demos

[edit]

Guidelines

[edit]

Setup

Autocompletion of input elements is a very helpful tool to guide users in entering the right value. That value can come from a (big) list of possible values or it may consist of values the user has entered before. This plugin makes it easy for developers to setup autocomplete for text inputs and textareas.

First step in setting up autocomplete is to decide what kind of data is provided. To autocomplete a few dozen possible values, it is a good idea to provide local data. The data is loaded only once and then cached, providing a very responsive interface. If the data can consist of hundreds, thousands or even millions of rows, the searching and filtering must be done where performance won't suffer, in most cases a relational database (eg. MySQL). The plugin will request the rows for the entered value, displaying only a subset of all possible values. For local autocomplete, just pass the data as an array to the autocomplete plugin. For remote autocomplete, specify a URL to the resource providing the data. The plugin then requests data with a "q" parameter containing the current search value.

[edit]

Dependencies between fields

Often one autocompleted field depends on the value of another field. In that case, the extraParams option can provide the necessary dynamic parameter:

Consider an example where the states-field reuses the value entered into the country field: 

$("#states").autocomplete(url, {
   extraParams: {
       country: function() { return $("#country").val(); }
   }
});

That way the serverside can return all states that have a country by that name.

[edit]

Stylesheets

The plugin provides the stylesheet jquery.autocomplete.css, which contains the necessary styling for the autocomplete itself, and only that. All class-selectors are namespaced with the "ac_"-prefix. Usually you can just use that and overwrite colors in your own stylesheet.

The package also contains demo/main.css, which is only for demo purposes.

[edit]

Search Page Replacement

An autocomplete plugin can be used to search for a term and redirect to a page associated with a resulting item. The following is one way to achieve the redirect: 

var data = [ {text:'Link A', url:'/page1'}, {text:'Link B', url: '/page2'} ];
$("...").autocomplete(data, {
  formatItem: function(item) {
    return item.text;
  }
}).result(function(event, item) {
  location.href = item.url;
});
Retrieved from "http://docs.jquery.com/Plugins/Autocomplete"