Demo (no JS, minimal options)

Note that by default you need to type at least 2 characters for the popup to show up, though that’s super easy to customize. With Awesomplete, making something like this can be as simple as:

<input class="awesomplete"
       data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />

// No extra JS needed for basic usage!

Basic usage

Before you try anything, you need to include awesomplete.css and awesomplete.js in your page, via the usual <link rel="stylesheet" href="awesomplete.css" /> and <script src="awesomplete.js" async></script> tags.

For the autocomplete, you just need an <input> text field (might work on <textarea> and elements with contentEditable, but that hasn’t been tested). Add class="awesomplete" for it to be automatically processed (you can still specify many options via HTML attributes), otherwise you can instantiate with a few lines of JS code, which allow for more customization.

There are many ways to link an input to a list of suggestions. The simple example above could have also been made with the following markup, which provides a nice native fallback in case the script doesn’t load:

<input class="awesomplete" list="mylist" />
<datalist id="mylist">
	<option>Ada</option>
	<option>Java</option>
	<option>JavaScript</option>
	<option>Brainfuck</option>
	<option>LOLCODE</option>
	<option>Node.js</option>
	<option>Ruby on Rails</option>
</datalist>

// None!

Or the following, if you don’t want to use a <datalist>, or if you don’t want to use IDs (since any selector will work in data-list):

<input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
	<li>Ada</li>
	<li>Java</li>
	<li>JavaScript</li>
	<li>Brainfuck</li>
	<li>LOLCODE</li>
	<li>Node.js</li>
	<li>Ruby on Rails</li>
</ul>

// None!

Or the following, if we want to instantiate in JS:

<input id="myinput" />
<ul id="mylist">
	<li>Ada</li>
	<li>Java</li>
	<li>JavaScript</li>
	<li>Brainfuck</li>
	<li>LOLCODE</li>
	<li>Node.js</li>
	<li>Ruby on Rails</li>
</ul>

var input = document.getElementById("myinput");
new Awesomplete(input, {list: "#mylist"});

We can use an element reference for the list instead of a selector:

<input id="myinput" />
<ul id="mylist">
	<li>Ada</li>
	<li>Java</li>
	<li>JavaScript</li>
	<li>Brainfuck</li>
	<li>LOLCODE</li>
	<li>Node.js</li>
	<li>Ruby on Rails</li>
</ul>

var input = document.getElementById("myinput");
new Awesomplete(input, {list: document.querySelector("#mylist")});

We can also directly use an array of strings:

<input id="myinput" />

var input = document.getElementById("myinput");
new Awesomplete(input, {
	list: ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"]
});

We can even set it (or override it) later and it will just work:

<input id="myinput" />

var input = document.getElementById("myinput");
var awesomplete = new Awesomplete(input);

/* ...more code... */

awesomplete.list = ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"];

Suggestions with different label and value are supported too. The label will be shown in autocompleter and the value will be inserted into the input. If you want to insert the label into the input you can provide your own replace function

<input id="myinput" />

var input = document.getElementById("myinput");

// Show label but insert value into the input:
new Awesomplete(input, {
	list: [
		{ label: "Belarus", value: "BY" },
		{ label: "China", value: "CN" },
		{ label: "United States", value: "US" }
	]
});

// Same with arrays:
new Awesomplete(input, {
	list: [
		[ "Belarus", "BY" ],
		[ "China", "CN" ],
		[ "United States", "US" ]
	]
});

// Show label and insert label into the input:
new Awesomplete(input, {
	list: [
		{ label: "Belarus", value: "BY" },
		{ label: "China", value: "CN" },
		{ label: "United States", value: "US" }
	],
	// insert label instead of value into the input.
	replace: function(suggestion) {
		this.input.value = suggestion.label;
	}
});

Customize

All settings discussed in this section are settable via either a data- attribute on the <input> element or a JS property on the second argument of the Awesomplete constructor, like so:

new Awesomplete(inputReference, {
	minChars: 3,
	maxItems: 15,
	...
});

You can of course combine both HTML attributes and JS properties. In case of conflict (e.g. you’ve specified both a data-minchars on the text field and a minChars JS property, the HTML attribute wins. You can also use the JS properties to change a parameter after the object has been created, in which case the change will apply even if there is a conflicting HTML attribute.

Extend

The following JS properties do not have equivalent HTML attributes, because their values are functions. They allow you to completely change the way Awesomplete works:

filter: function (text, input) {
	return text.indexOf(input) === 0;
}

function (text) {
	this.input.value = text;
}

data: function (item, input) {
	return { label: item.name, value: item.id };
}

list: [ new Date("2015-01-01"), ... ] 

Events

Custom events are thrown in several places and are often cancellable. To avoid conflicts, all custom events are prefixed with awesomplete-.

API

There are several methods on every Awesomplete instance that you can call to customize behavior:

Advanced Examples

These examples show how powerful Awesomplete’s minimal API can be.

<input type="email" />

<input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" data-multiple />

<input id="query" class="awesomplete"  />

<input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" class="dropdown-input" />