Documentation

UI/Autocomplete

From jQuery JavaScript Library

Jump to: navigation, search

« Back to the jQuery UI Docs

Contents

[edit]

Important Information

As of jQuery UI 1.7, the autocomplete plugin is not part of the stable release of jQuery UI.

Development plans for this functionality and the inclusion of this plugin's functions can be read about here; http://wiki.jqueryui.com/Autocomplete

The current repository version of this plugin can be found here: http://jquery-ui.googlecode.com/svn/branches/dev/autocomplete/

The original plugin is still available for download, and while not being updated for some time also works with current jQuery versions, as well as 1.2.6: http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/

[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.

NameType
Dependencies:

  • ui.core.js

NameType

NameType
Plugin methods:




NameType
autocomplete( options )Returns: jQuery
Make the selected elements Autocomplete.
autocomplete( "result", handler )Returns: jQuery
Handle the result of a search event.
autocomplete( "search" )Returns: jQuery
Trigger a search event.
autocomplete( "flushCache" )Returns: jQuery
Flush (empty) the cache of matched input's autocompleters.
autocomplete( "setData", options )Returns: jQuery
Updates the options for the current autocomplete field.
autocomplete( "destroy" )Returns: jQuery
Completely remove the autocomplete.


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/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>

NameType

[edit]

Demos

[edit]

Guidelines

When specifying the data, write it this way:
$("#example").autocomplete( {data:data} );

The example shown here will not work with recent versions of jQueryUI

[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, SQL Server, or cached in server memory). 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. If you are using the default settings your page should output the filtered results simply as plain text separated by line breaks (not HTML, not JSON). If you need to do something more advanced you can define item formatting functions that will take each raw data line and return the text you want to display.

[edit]

CSS Setup

You will also need to set up some styles. You can do this either using Themeroller or by adding your own stylesheet. Below are the default styles. You can copy these into your own stylesheet. 

.ui-autocomplete-results {
	padding: 0px;
	border: 1px solid black;
	background-color: white;
	overflow: hidden;
	z-index: 99999;
}

.ui-autocomplete-results ul {
	width: 100%;
	list-style-position: outside;
	list-style: none;
	padding: 0;
	margin: 0;
}

.ui-autocomplete-results li {
	margin: 0px;
	padding: 2px 5px;
	cursor: default;
	display: block;
	/* 
	if width will be 100% horizontal scrollbar will apear 
	when scroll mode will be used
	*/
	/*width: 100%;*/
	font: menu;
	font-size: 12px;
	/* 
	it is very important, if line-height not setted or setted 
	in relative units scroll will be broken in firefox
	*/
	line-height: 16px;
	overflow: hidden;
}

.ui-autocomplete-loading {
	background: white url('indicator.gif') right center no-repeat;
}

.ui-autocomplete-odd {
	background-color: #eee;
}

.ui-autocomplete-over {
	background-color: #0A246A;
	color: white;
}

Note: in previous versions of jQuery UI, the autocomplete classes were prefixed by ".ac_" instead of ".ui-autocomplete-".

Retrieved from "http://docs.jquery.com/UI/Autocomplete"