Skip to content
This repository has been archived by the owner on Mar 16, 2018. It is now read-only.

Options

Jump to bottom
Klap-in edited this page Nov 17, 2012 · 8 revisions

autocomplete( url or data, [options] )

$("#tags").autocomplete("search.php");

$("#tags").autocomplete(["c++", "java", "php", "coldfusion", "javascript", "asp"], {
	max: 4,
	highlight: false
});

var aData = var data = "Core Selectors Attributes Traversing Manipulation Ajax Utilities".split(" ");
$("#tags").autocomplete( aData, {
	max: 4,
	highlight: false
});

$("#tags").autocomplete("search.php", {
	max: 4,
	highlight: false
});

autoFill Boolean
Default: false

Fill the textinput while still selecting a value, replacing the value if more is typed or something else is selected.

cacheLength Number Default: 10

The number of backend query results to store in cache. If set to 1 (the current result), no caching will happen. Must be >= 1.

clickFire Boolean
Default: false

Option to activate select list with one click instead of two.

dataType String
default: not defined, should be 'html'.

Defines dataType for the ajax request

Example:

We expected jsonp as data format, for example for requests to geonames.org.

dataType: 'jsonp',

delay Number
Default: 400 for remote, 10 for local

The delay in milliseconds the autocompleter waits after a keystroke to activate itself.

extraParams Object

Extra parameters for the backend. If you were to specify { bar:4 }, the autocompleter would call my_autocomplete_backend.php?q=foo&bar=4 (assuming the input box contains "foo"). The param can be a function that is called to calculate the param before each request.

Example:

extraParams: {
   // geonames doesn't support q and limit, which are the autocomplete plugin defaults, so let's blank them out.
	q: '',
	limit: '',
	country: 'US',
	featureClass: 'P',
	style: 'full',
	maxRows: 50,
	name_startsWith: function () { return $("#city").val() }
},

failure Function
Default: Same callback is used as success or a results are hidden

Sets a global failure function that's executed when ajax request fails. It overrides the other failure functions.

No parameters are provided.

formatItem Function
Default: returns the first entry of row.

For each row of results, this function will be called.
Autocompleter will provide 5 parameters to formatItem(row, i, max, value, term):

  • row: the results row,
  • i: the position of the row in the list of results (starting at 1),
  • max: the number of items in the list of results
  • value: the value of row (default parser returns here row[0])
  • term: the search term.

The returned value will be displayed inside an LI element in the results list. When it returns false Autocompleter won't add the value to the results list.

Example:

Items in the result list of autocomplete are extended by the adminCode1 field, what is the state. So it will show "Chicago, IL". This sets only the appearance of the list items. Not of the value added to the input.

formatItem: function(row, i, n) {
	return row.name + ', ' + row.adminCode1;
},

formatMatch Function
Default: formatItem is used

Autocompleter will provide 3 parameters to formatMatch(row, i, max):

  • row: the results row,
  • i: the position of the row in the list of results (starting at 1),
  • max: the number of items in the list of results

Use this option if you want to limit the data that autocomplete searches for matches. The returned value is used to build a lookup list. Only used for matching on local data source. When it returns false Autocompleter won't add the value to the match list.

formatResult Function
Default: returns value (the first entry of row)

Autocompleter will provide 2 parameters to formatResult(row, value):

  • row: the raw response row
  • value: remote data source: the value of row (is equal to row[0]) or local data source: output of formatMatch

For remote data source this function is used in parse() and for a local data source this function is used after matching. The returned value will be put into the input field.

highlight Boolean, Function
Default: Wraps the search term in a <strong> element

Autocompleter will provide 2 parameters to highlight(formattedvalue, term):

  • formattedvalue: output of formatItem
  • term: the search term.

When highlight option is set to false it returns formattedvalue without modifications. Otherwise it uses the default highlight function to wrap the search term in a <strong> element. Set to a function to customize.

The default highlight function:

highlight: function(value, term) {
		return value.replace(new RegExp("(?![^&;]+;)(?!<[^<>]*)(" + term.replace(/([\^\$\(\)\[\]\{\}\*\.\+\?\|\\])/gi, "\\$1") + ")(?![^<>]*>)(?![^&;]+;)", "gi"), "<strong>$1</strong>");
}

inputFocus Boolean
Default: true

Option to forgo input focus on item select. inputFocus is set to true by default, but setting it to false in the options will cancel this behavior.

matchCase Boolean
Default: false

Whether or not the comparison is case sensitive. Important only if you use caching.

matchContains Boolean
Default: false

Whether or not the comparison looks inside (i.e. does "ba" match "foo bar") the search results. Important only if you use caching. Don't mix with autofill.

matchSubset Boolean
Default: true

Whether or not the autocompleter can use a cache for more specific queries. This means that all matches of "foot" are a subset of all matches for "foo". Usually this is true, and using this options decreases server load and increases performance. Only useful with cacheLength settings bigger than one, like 10.

max Number
Default: 150

Limit the number of items in the select box. Is also sent as a "limit" parameter with a remote request. When scroll is false, default max is 10, otherwise the default value of max is 150.

minChars Number
Default: 1

The minimum number of characters a user has to type before the autocompleter activates.

multiple Boolean
Default: false

Whether to allow more than one autocompleted-value to enter.

multipleSeparator String
Default: " "

Seperator to put between values when using multiple option.

mustMatch Boolean
Default: false

If set to true, the autocompleter will only allow results that are presented by the backend. Note that illegal values result in an empty input box.

parse Function
Default: function that split ajax response in rows on "\n" and fields on "|".

Only called when parsing the response of remote data source. Autocompleter will provide 1 parameter to parse(data):

  • data: response of jQuery.ajax

The returned value is an array of objects. Each object contains:

  • data: array of the entries of response row
  • value: first entry of respons row (row[0]), is 4th argument for formatItem
  • result: the output of formatResult

You may choose your own format of the data in the response of the remote data source (check dataType too, when you consider e.g. json). This parse() function is then needed to parse this into the desired format. Of course you can already format data on the remote source and return it as json, so parse() only relays the result:

parse: function (result) {
	return result;
}

Example:

A function to parse what geonames.org returns. Here isn't used formatResult() for generating the result value. The default parse() calls formatResult(row, row[0]), but when you write your own parse(), you are free in your design of formatResult() or you can leave it out.

parse: function(data) {
	var rows = new Array();
	data = data.geonames;
	for(var i=0; i<data.length; i++){
		rows[i] = { data:data[i], value:data[i].name, result:data[i].name };
	}
	return rows;
},

scroll Boolean
Default: true

Whether to scroll when more results than configured via scrollHeight are available.
When scroll is false, the default value of max is 10, otherwise 150. Of course adding the max option override this.

scrollHeight Number
Default: 180

height of scrolled autocomplete control in pixels

scrollJumpPosition Boolean
Default: true

When moving with keyup/down the cursor jump some entries back when the list scrolls and reaching the end/begin of the list jumps back to the first/last entry. Setting to false disable all these jumping behaviour.

selectFirst Boolean
Default: true

If this is set to true, the first autocomplete value will be automatically selected on tab/return, even if it has not been handpicked by keyboard or mouse action. If there is a handpicked (highlighted) result, that result will take precedence.

width Number
Default: width of the input Element

Specify a custom width for the select box.

inputClass String
default: "ac_input"

Class added to the input.

resultsClass String
default: "ac_results"

Class of div containing the results list.

loadingClass String
default: "ac_loading"

Classe added to the input during loading.

##Example:

Here a combination of some options. This example autocompletes input element with id #city. It collects example fragments used above. This example is from http://1300grams.com/2009/08/17/jquery-autocomplete-with-json-jsonp-support-and-overriding-the-default-search-parameter-q/, this site has also an extended description of the options.

$("#city").autocomplete("http://ws.geonames.org/searchJSON", {
	dataType: 'jsonp',
	parse: function(data) {
		var rows = new Array();
		data = data.geonames;
		for(var i=0; i<data.length; i++){
			rows[i] = { data:data[i], value:data[i].name, result:data[i].name };
		}
		return rows;
	},
	formatItem: function(row, i, n) {
		return row.name + ', ' + row.adminCode1;
 		},
	extraParams: {
		// geonames doesn't support q and limit, which are the autocomplete plugin defaults, so let's blank them out.
		q: '',
		limit: '',
		country: 'US',
		featureClass: 'P',
		style: 'full',
		maxRows: 50,
		name_startsWith: function () { return $("#city").val() }
	},
	max: 50
});
Clone this wiki locally