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.

<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" ]
	]
});

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 data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" class="dropdown-input" />