Jquery easyAutocomplete documentation and usage guide

Basics

EasyAutocomplete plugin is very simple to use. Just call function easyAutocomplete on a input field and give it a list of elements to display. That's it.

Example:

<input id="basics" />

var options = {
	data: ["blue", "green", "pink", "red", "yellow"]
};

$("#basics").easyAutocomplete(options);

Data providers

Data providers - simple .js file

Connect EasyAutocomplete plugin to the external data source. In this example, I have used data file with simple array of colors. File is located on same server("resources/color.json"), so parameter url needs to be resources/colors.json.

Example:

	
["red", "green", "blue", " black", "yellow"]
	

<input id="provider-file" />

var options = {
	url: "resources/colors.js"
};

$("#provider-file").easyAutocomplete(options);

Data providers - json

You can connect EasyAutocomplete plugin to a json data provider. In the example below, plugin loads(via ajax) data from json file, located on the same server. Location of the file needs to be specified in the url parameter. Plugin loads data from the file countries.json, that contains country names and codes. Single elements has format: {"name": "Afghanistan", "code": "AF"}. The last thing you need to do, is to specify parameter getValue, so that the plugin will display correct value on the autocomplete list. It will get value out of the json object.

For better understanding of this example matching is enabled. Countries.json is just a json file with all the countries.

Example:

	
[
  {"name": "Afghanistan", "code": "AF"},
  {"name": "Aland Islands", "code": "AX"},
  {"name": "Albania", "code": "AL"},
  {"name": "Algeria", "code": "DZ"},
  {"name": "American Samoa", "code": "AS"},
  ...
 ]
	

<input id="provider-json" />

var options = {
	url: "resources/countries.json",

	getValue: "name",

	list: {
		match: {
			enabled: true
		}
	}
};

$("#provider-json").easyAutocomplete(options);

GetValue as function

Parameter getValue doesn't necessary need to be a string. If you are using more complex data, you can declare function that will be used to get value out of the element. For example above you can use:

	
getValue: function(element) {
	return element.name;
}
	

Data providers - xml

EasyAutocomplete plugin can be connected to an xml data provider. It requires more configuration than json, but nothing is overly complex with this jquery autocomplete plugin. As you can see in the example below, plugin loads data from xml file(it doesn't need to be a file, you can use a service, that gives response in xml format). You need to specify, that you will use xml data, so set the parameter to dataType: "xml". Xml file contains names of all the countries. Structure of xml is displayed below. Single element <country> consists of name and iso code. Plugin needs to know where to find elements of the data, so you have to specify node name xmlElementName: "country". Additionaly, you need to write a function that will take value out of the element(see parameter getValue).

Matching is enabled, because countries.xml is just an xml file with all the countries.

Example:

	
<?xml version="1.0" encoding="utf-8"?>
<countries>
	<country>
		<name>Afghanistan</name><iso>AF</iso>
	</country>
	<country>
		<name>Aland Islands</name><iso>AX</iso>
	</country>
	<country>
		<name>Albania</name><iso>AL</iso>
	</country>
	<country>
		<name>Algeria</name><iso>DZ</iso>
	</country>
	<country>
		<name>American Samoa</name><iso>AS</iso>
	</country>
  	...
</countries>
	

<input id="provider-xml" />

var options = {
	url: "resources/countries.xml",

	dataType: "xml",
	xmlElementName: "country",

	getValue: function(element) {
		return $(element).find("name").text();
	},

	list: {
		match: {
			enabled: true
		}
	}
};

$("#provider-xml").easyAutocomplete(options);

Complex getValue

Here parameter getValue is a function, that gets name value out of the xml element.

	
getValue: function(element) {
	return $(element).find("name").text();
}
	

Data providers - remote example

EasyAutomomplete can take data not only from json / xml files, but can also be connected to an api. The next example uses ajax to get list of countries depending on input phrase. Service generates json response with countries, that matches phrase from field. You can try how it works: country search. In the options used for this example, you can see property url as a function, that takes phrase and sends it to an api. Response from service is converted to the list with suggestions.

Single elements has a format {"name": "Afghanistan", "code": "AF"}, so if you want to show all the countries names, parameter getValue need to take the value "name".

Example:

<input id="provider-remote" />

var options = {
	url: function(phrase) {
		return "api/countrySearch.php?phrase=" + phrase + "&format=json";
	},

	getValue: "name"
};

$("#provider-remote").easyAutocomplete(options);

Ajax settings

EasyAutocomplete uses jQuery method ajax for making data requests. Full documentation on this method can be found in the jQuery website. As you can see ajax method has a lot of different settings and can be used in a lot of different ways.

EasyAutocomplete lets you use jquery ajax settings via parameter ajaxSettings. This parameter is used in jquery ajax invoke, simply $.ajax(ajaxSettings), so that gives you many ways to configure this plugin.

For better understanding how this works, check out this duckduckgo autocomplete example.

Asynchronous responses

Easyautocomplete sends requests asynchronously by default(synchronous connections may cause browser to hang). Working with remote services/servers that needs time to generate data always gives some issues. Mainly because you cannot always know how long it will take service to respond.

Easyautocomplete sends request each time input changes its value, so when you type 6 letter word "phrase" there will be 6 requests sended to the service. You cannont know which of the 6 responses will come last, so you don't know if autocomplete list shows suggestions for your word "phrase". It can show suggestions for 5 letter "phras", because you cannot be sure which of the 6 requests come last.

To resolve this issue your service can sent back input phrase and EasyAutocomplete will compare it with the actual input value. To make it work you need to set paramater matchResponseProperty to value where in response is located query value. For the example below I have specified matchResponseProperty: "inputPhrase", because response.json holds query value in parameter "inputPhrase".

This example will show autocomplete list only if you match static response so type "eac".

Example:

	
{
	"items": [
 		"red", "yellow", "brown"
	],
	"inputPhrase": "eac"
}
	

<input id="response-async" />

var options = {
	url: "resources/response.json",

	listLocation: "items",

	matchResponseProperty: "inputPhrase"
};

$("#response-async").easyAutocomplete(options);

This example uses parameter listLocation, which describes where autocomplete data list is located in json response.

List location

When your response data is more complex, you can specify the location of the list. In the example below, I've used sample google maps json file. List is located under property "markers", so option listLocation should be set to "markers".

Example:

	
{"markers": [
        {
            "point": "new GLatLng(40.266044,-74.718479)",
            "homeTeam":"Lawrence Library",
            "awayTeam":"LUGip",
            "markerImage":"images/red.png",
            "information": "Linux users group meets second Wednesday of each month.",
            "fixture":"Wednesday 7pm",
            "capacity":"",
            "previousScore":""
        },
        ...
        ]
    }
	

<input id="listLocation" />

var options = {
	url: "resources/maps.json",

	listLocation: "markers",

	getValue: "homeTeam"
};

$("#listLocation").easyAutocomplete(options);

Parameter listLocation can be either string or function.

Color themes

Select one of the color themes:

• dark
• blue
• purple
• yellow
• blue-light
• green-light
• bootstrap

Example:

<input id="theme" />

var options = {
	
	data: ["Cyclops", "Storm", "Mystique", "Wolverine", "Professor X", "Magneto"],
	
	theme: "dark"
};

$("#theme").easyAutocomplete(options);

You can find more interesting themes in EasyAutocomplete - jquery autocomplete - themes section.

Select theme

Theme can be specified by parameter theme.

Custom css classes

You can also add your own css style classes. Declare them in parametercssClasses.

Templates

EasyAutocomplete lets you modify the view of suggestions list. On the EasyAutocomplete - jQuery autocomplete - home page, I have created three examples that use different templates for displaying lists. The first example, "countries", uses simple default list view. The second example, the "countries with flags", uses custom template which, in addition to country name, displays also its flag. The third example, "super heroes", displays heroes names and its miniature head. To do that, example uses build in template called "iconRight".

Templating feature has a couple of build in views for a list:

• description
• iconLeft
• iconRight
• links
• custom

	
<input id="template-desc" />
	

	
var options = {
	data: [ {name: "Avionet", type: "air", icon: "http://lorempixel.com/100/50/transport/2"},
		{name: "Car", type: "ground", icon: "http://lorempixel.com/100/50/transport/8"},
		{name: "Motorbike", type: "ground", icon: "http://lorempixel.com/100/50/transport/10"},
		{name: "Plane", type: "air", icon: "http://lorempixel.com/100/50/transport/1"},
		{name: "Train", type: "ground", icon: "http://lorempixel.com/100/50/transport/6"}],

	getValue: "name",

	template: {
		type: "description",
		fields: {
			description: "type"
		}
	}
};

$("#template-desc").easyAutocomplete(options);
	

	
<input id="template-icon-left" />
	

	
var options = {
	data: [ {name: "Avionet", type: "air", icon: "http://lorempixel.com/100/50/transport/2"},
		{name: "Car", type: "ground", icon: "http://lorempixel.com/100/50/transport/8"},
		{name: "Motorbike", type: "ground", icon: "http://lorempixel.com/100/50/transport/10"},
		{name: "Plane", type: "air", icon: "http://lorempixel.com/100/50/transport/1"},
		{name: "Train", type: "ground", icon: "http://lorempixel.com/100/50/transport/6"}],

	getValue: "name",

	template: {
		type: "iconLeft",
		fields: {
			iconSrc: "icon"
		}
	}
};

$("#template-icon-left").easyAutocomplete(options);
	

	
<input id="template-icon-right" />
	

	
var options = {
	data: [ {name: "Avionet", type: "air", icon: "http://lorempixel.com/100/50/transport/2"},
		{name: "Car", type: "ground", icon: "http://lorempixel.com/100/50/transport/8"},
		{name: "Motorbike", type: "ground", icon: "http://lorempixel.com/100/50/transport/10"},
		{name: "Plain", type: "air", icon: "http://lorempixel.com/100/50/transport/1"},
		{name: "Train", type: "ground", icon: "http://lorempixel.com/100/50/transport/6"}],


	getValue: "name",

	template: {
		type: "iconRight",
		fields: {
			iconSrc: "icon"
		}
	}
};

$("#template-icon-right").easyAutocomplete(options);
	

	
<input id="template-links" />
	

	
var options = {
    data: [
        {"text": "Home", "website-link": "http://easyautocomplete.com/"},
        {"text": "Guide", "website-link": "http://easyautocomplete.com/guide"},
        {"text": "Themes", "website-link": "http://easyautocomplete.com/themes"},
        {"text": "Examples", "website-link": "http://easyautocomplete.com/examples"},
        {"text": "Download", "website-link": "http://easyautocomplete.com/download"},
        {"text": "Github", "website-link": "https://github.com/pawelczak/EasyAutocomplete"}
    ],

    getValue: "text",

    template: {
        type: "links",
        fields: {
            link: "website-link"
        }
    }
};

$("#template-links").easyAutocomplete(options);
	

	
<input id="template-custom" />
	

	
var options = {
	data: [ {name: "Avionet", type: "air", icon: "http://lorempixel.com/100/50/transport/2"},
		{name: "Car", type: "ground", icon: "http://lorempixel.com/100/50/transport/8"},
		{name: "Motorbike", type: "ground", icon: "http://lorempixel.com/100/50/transport/10"},
		{name: "Plain", type: "air", icon: "http://lorempixel.com/100/50/transport/1"},
		{name: "Train", type: "ground", icon: "http://lorempixel.com/100/50/transport/6"}],


	getValue: "name",

	template: {
		type: "custom",
		method: function(value, item) {
			return "<img src='" + item.icon + "' /> | " + item.type + " | " + value;
		}
	}
};

$("#template-custom").easyAutocomplete(options);
	

Categories

Categories feature is a very useful tool, that lets creating suggestion list consisting of items from couple of different sources.

Section contains information on:

• basics

	
{
    "fruits": ["Apple", "Cherry", "Clementine", "Honeydew melon", "Watermelon", "Satsuma"],
    "vegetables": ["Pepper", "Jerusalem artichoke", "Green bean", "Fennel", "Courgette", "Yam"]
}
	

	
  <input id="categories-basic" />
	

	
var options = {
    url: "resources/fruitsAndVegetables.json",

    categories: [
        {   //Category fruits
            listLocation: "fruits",
            header: "-- Fruits --"
        },
        {   //Category vegetables
            listLocation: "vegetables",
            header: "-- Vegetables --"
        }
    ]

};

$("#categories-basic").easyAutocomplete(options);
	

Events

EasyAutocomplete allows you to invoke function in couple moments. This feature is really helpful when you need to run some code when suggestion list is loaded.

In example below function will be called each time user clicks on one of items on suggestions list.

Example:

<input id="trigger-event" />

var options = {
	url: "resources/countries.json",

	getValue: "name",

	list: {
		onClickEvent: function() {
			alert("Click !");
		}	
	}
};

$("#trigger-event").easyAutocomplete(options);

EasyAutocomplete lets you invoke functions in couple of different moments:

Functions

Extension EasyAutocomplete has a couple of helpful functions.

Function .getSelectedItemIndex()

Function getSelectedItemIndex returns index of the actual selected item from autocomplete list. Function needs to be invoked on jquery object, that represents input text field.

Example below shows how getSelectedItemIndex works.

Example:

	
<input id="function-index" />
<input id="index-holder" />
	

	
var options = {
	data: ["Superman", "Wonder Woman", "Iron Man", "Batman", "Catwoman"],
	list: {

		onSelectItemEvent: function() {
			var index = $("#function-index").getSelectedItemIndex();

			$("#index-holder").val(index).trigger("change");
		}
	}
};

$("#function-index").easyAutocomplete(options);
	

Function .getSelectedItemData()

Function getSelectedItemData returns value of selected item. If array of items contains string, function returns string value. If array contains objects, function returns objects. Funciton needs to be invoked on jquery object, that represents input text field.

Example below shows how getSelectedItemData works.

Example:

	
<input id="function-data" />
<input id="data-holder" />
	

	
var options = {
	data: [
		{"character": "Cyclops", "realName": "Scott Summers"},
		{"character": "Professor X", "realName": "Charles Francis Xavier"},
		{"character": "Mystique", "realName": "Raven Darkholme"},
		{"character": "Magneto", "realName": "Max Eisenhardt"}
		],

	getValue: "character",

	list: {

		onSelectItemEvent: function() {
			var value = $("#function-data").getSelectedItemData().realName;

			$("#data-holder").val(value).trigger("change");
		}
	}
};

$("#function-data").easyAutocomplete(options);
	

Function .getItemData(index)

Function getItemData returns value of item specified by argument index. If array of items contains string, function returns string value. If array contains objects, function returns objects. Funciton needs to be invoked on jquery object, that represents input text field.

Animation

EasyAutocomplete plugin allows you to choose, how you want elements list to appear. You can select animation for two actions: show list and hide list. That corresponds to configuration options showAnimation and hideAnimation for show and hide action respectively. You can choose one of three different animation types: fade, slide, normal. Fade animation makes a list appear by changing it's opacity value. Slide animation makes the list slide from above, when show action is runned and slide up, when hide action is runned. Normal type of animation makes list just appear or disappear(no fancy effect).

You can also specify the animation time and declare function that will be runned when the animation will finish(callback).

Example:

<input id="animation" />

var options = {
	url: "resources/countries.json",

	getValue: "name",

	list: {
		showAnimation: {
			type: "fade", //normal|slide|fade
			time: 400,
			callback: function() {}
		},

		hideAnimation: {
			type: "slide", //normal|slide|fade
			time: 400,
			callback: function() {}
		}
	}
};

$("#animation").easyAutocomplete(options);

Default animation type is "normal", so no fancy animation.

Match phrase

Feature match is really helpful when you have a long list of elements. You probably want your autocomplete list to show only elements, that match value written in the input field. That's where match comes in handy.

Example:

<input id="match" />

var options = {
	data: ["Clark Kent", "Diana Prince", "Tony Stark", "Bruce Wayne", "Selina Kyle"],
	list: {
		match: {
			enabled: true
		}
	}
};

$("#match").easyAutocomplete(options);

Option match is disabled by default.

Sort list

Sort feature enables you to decide about the order in which elements should appear on the list. You can use basic alphabetical sort or reverse alphabetical sort.

Example:

<input id="sort" />

var options = {
	//super heroes
	data: ["Superman", "Wonder Woman", "Iron Man", "Batman", "Catwoman"],
	list: {
		sort: {
			enabled: true
		}
	}
};

$("#sort").easyAutocomplete(options);

Option sort is disabled by default.

List size

You can decide how many elements should appear on the list.

Example:

<input id="maxsize" />

var options = {
	//fruits
	data: [
		"apples",
		"apricot",
		"avocado",	
		"bananas",
		"blueberries",
		"cherries",
		"grapefruit",
		"grapes",
		"kiwi fruit",
		"lemons",
		"mangoes",	
		"melons",
		"nectarines",
		"oranges",
		"passion fruit",
		"peaches",	
		"pears",
		"pineapples",
		"plums",
		"rhubarb",
		"rock melon",
		"strawberries",
		"watermelon"
		],
	list: {
		maxNumberOfElements: 10,
		match: {
			enabled: true
		}
	}
};

$("#maxsize").easyAutocomplete(options);

Default value for parameter maxNumberOfElements is 6.

Request data delay

EasyAutocomplete jquery extension lets you delay data request calls. This feature is really helpful, when preparing ajax response data takes alot of resources. It is good to avoid sending multiple request data, when user types couple of letters in text field. Using parameter requestDelay: 500 delays jquery ajax call by 500 miliseconds, so when user types fast the request will be called when user stops typing. Instead of one request for one letter inserted in text field.

Example:

<input id="sort" />

var options = {
	url: function(phrase) {
		return "api/countrySearch.php?phrase=" + phrase + "&format;=json";
	},

	getValue: "name",
	
	requestDelay: 500
};

$("#request-delay").easyAutocomplete(options);

Option requestDelay is setted up to 0 miliseconds by default(no delay), but it can any number of miliseconds.

Highlight

Plugin has option to highlight matched phrase on elements list.

In all the previous examples highligthing has been enabled, so phrase has been highlighted on the autocomplete elements list. That's because option highlightPhrase has, by default, the value true. In order to demonstrate change in autocomplete behaviour, in the fallowing example highligthing will be disabled.

Example:

<input id="not-highlighted" />

var options = {
	url: "resources/countries.json",

	getValue: function(element) {
		return element.name;
	},

	highlightPhrase: false
};

$("#not-highlighted").easyAutocomplete(options);

Default value for option highlightPhrase is true.

Placeholder

Define input's placeholder.

Example:

<input id="placeholder" />

var options = {
	data: ["Superman", "Wonder Woman", "Iron Man", "Batman", "Catwoman"],
	placeholder: "Set up placeholder value"
};

$("#placeholder").easyAutocomplete(options);