awesomplete

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <title>Awesomplete: Ultra lightweight, highly customizable, simple autocomplete, by Lea Verou</title> <link rel="stylesheet" href="prism/prism.css" /> <link rel="stylesheet" href="awesomplete.css" /> <link rel="stylesheet" href="style.css" /> <script src="awesomplete.js"></script> <script src="index.js"></script> </head> <body class="language-markup"> <header> <h1>Awesomplete</h1> <a href="#download" class="size"><strong>2KB</strong> minified <span class="amp">&</span> gzipped!</a> <p>Ultra lightweight, customizable, simple autocomplete widget with zero dependencies, built with modern standards for <abbr title="Verified to work in: IE9 (sorta), IE10+, Chrome, Firefox, Safari 5+, Mobile Safari">modern browsers</abbr>. <a href="http://lea.verou.me/2015/02/awesomplete-2kb-autocomplete-with-zero-dependencies">Because <code><datalist></code> still doesn’t cut it.</a></p> <nav></nav> </header> <section> <h1>Demo (no JS, minimal options)</h1> <label> Pick a programming language:<br /> <input autofocus class="awesomplete" data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" /> </label> <p>Note that by default you need to type <strong>at least 2 characters</strong> for the popup to show up, though that’s <a href="#customization">super easy to customize</a>. With Awesomplete, making something like this can be as simple as:</p> <pre class="language-markup"><code><input class="awesomplete" data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" /></code></pre> <pre class="language-javascript"><code>// No extra JS needed for basic usage!</code></pre> </section> <section id="basic-usage"> <h1>Basic usage</h1> <p>Before you try anything, you need to include <code>awesomplete.css</code> and <code>awesomplete.js</code> in your page, via the usual <code><link rel="stylesheet" href="awesomplete.css" /></code> and <code><script src="awesomplete.js" async></script></code> tags.</p> <p>For the autocomplete, you just need an <code><input></code> text field (might work on <code><textarea></code> and elements with <code>contentEditable</code>, but that hasn’t been tested). Add <code>class="awesomplete"</code> for it to be <strong>automatically processed</strong> (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.</p> <p>There are many ways <strong>to link an input to a list of suggestions</strong>. 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:</p> <pre class="language-markup"><code><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></code></pre> <pre class="language-javascript"><code>// None!</code></pre> <p>Or the following, if you don’t want to use a <code><datalist></code>, or if you don’t want to use IDs (since any selector will work in <code>data-list</code>):</p> <pre class="language-markup"><code><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></code></pre> <pre class="language-javascript"><code>// None!</code></pre> <p>Or the following, if we want to instantiate in JS:</p> <pre class="language-markup"><code><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></code></pre> <pre class="language-javascript"><code>var input = document.getElementById("myinput"); new Awesomplete(input, {list: "#mylist"});</code></pre> <p>We can use an <strong>element reference</strong> for the list instead of a selector:</p> <pre class="language-markup"><code><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></code></pre> <pre class="language-javascript"><code>var input = document.getElementById("myinput"); new Awesomplete(input, {list: document.querySelector("#mylist")});</code></pre> <p>We can also directly use an <strong>array of strings</strong>:</p> <pre class="language-markup"><code><input id="myinput" /></code></pre> <pre class="language-javascript"><code>var input = document.getElementById("myinput"); new Awesomplete(input, { list: ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"] });</code></pre> <p>We can even set it (or override it) later and it will just work:</p> <pre class="language-markup"><code><input id="myinput" /></code></pre> <pre class="language-javascript"><code>var input = document.getElementById("myinput"); var awesomplete = new Awesomplete(input); /* ...more code... */ awesomplete.list = ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"];</code></pre> <p>Suggestions with different <strong>label</strong> and <strong>value</strong> are supported too. The label will be shown in autocompleter and the <strong>value</strong> will be inserted into the input. If you want to insert the label into the input you can provide your own <strong>replace</strong> function</p> <pre class="language-markup"><code><input id="myinput" /></code></pre> <pre class="language-javascript"><code>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; } }); </code></pre> </section> <section id="customization"> <h1>Customize</h1> <p>All settings discussed in this section are settable via either a <code>data-</code> attribute on the <code><input></code> element or a JS property on the second argument of the <code>Awesomplete</code> constructor, like so:</p> <pre class="language-javascript"><code>new Awesomplete(inputReference, { minChars: 3, maxItems: 15, ... });</code></pre> <p>You can of course combine both HTML attributes and JS properties. <strong>In case of conflict</strong> (e.g. you’ve specified both a <code>data-minchars</code> on the text field and a <code>minChars</code> JS property, <strong>the HTML attribute wins</strong>. You can also use the JS properties to change a parameter <strong>after</strong> the object has been created, in which case the change will apply even if there is a conflicting HTML attribute.</p> <table> <thead> <tr> <th>JS property</th> <th>HTML attribute</th> <th>Description</th> <th>Value</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>list</code></td> <td><code>data-list</code></td> <td>Where to find the list of suggestions. Described in more detail in the “<a href="#basic-usage">Basic usage</a>” section above.</td> <td><ul> <li>Array of strings</li> <li>HTML element</li> <li>CSS selector (no groups, i.e. no commas)</li> <li>String containing a comma-separated list of items</li> </ul></td> <td>N/A</td> </tr> <tr> <td><code>minChars</code></td> <td><code>data-minchars</code></td> <td>Minimum characters the user has to type before the autocomplete popup shows up.</td> <td>Number</td> <td>2</td> </tr> <tr> <td><code>maxItems</code></td> <td><code>data-maxitems</code></td> <td>Maximum number of suggestions to display.</td> <td>Number</td> <td>10</td> </tr> <tr> <td><code>autoFirst</code></td> <td><code>data-autofirst</code></td> <td>Should the first element be automatically selected? Demo: <input class="awesomplete" data-autofirst data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" xautofocus /></td> <td>Boolean</td> <td>false</td> </tr> <tr> <td><code>tabSelect</code></td> <td><code>data-tabSelect</code></td> <td>Should the first element be selected when the user hits the TAB key when the field has focus?></td> <td>Boolean</td> <td>false</td> </tr> <tr> <td><code>listLabel</code></td> <td><code>data-listlabel</code></td> <td>Denotes a label to be used as aria-label on the generated autocomplete list.</td> <td>String</td> <td>Results List</td> </tr> </tbody> </table> </section> <section id="extensibility"> <h1>Extend</h1> <p>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:</p> <table> <thead> <tr> <th>Property</th> <th>Description</th> <th>Value</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>filter</code></td> <td>Controls how entries get matched. By default, the input can match anywhere in the string and it’s a case insensitive match.</td> <td>Function that takes two parameters, the first one being the current suggestion text that’s being tested and the second a string with the user’s input it’s matched against. Returns <code>true</code> if the match is successful and <code>false</code> if it is not. For example, to only match strings that <strong>start with the user’s input</strong>, <strong>case sensitive</strong>, we can do this: <pre class="language-javascript"><code>filter: function (text, input) { return text.indexOf(input) === 0; }</code></pre> For case-<strong>in</strong>sensitive matching from the start of the word, there is a predefined filter that you can use, <code class="language-javascript">Awesomplete.FILTER_STARTSWITH</code> </td> <td><code class="language-javascript">Awesomplete.FILTER_CONTAINS</code>: Text can match anywhere, case insensitive.</td> </tr> <tr> <td><code>sort</code></td> <td>Controls how list items are ordered.</td> <td>Sort function (will be passed directly to <code>Array.prototype.sort()</code>) to sort the items after they have been filtered and before they are truncated and converted to HTML elements. If value is <code>false</code>, sorting will be disabled.</td> <td>Sorted by length first, order second.</td> </tr> <tr> <td><code>container</code></td> <td>Controls how list container element is generated.</td> <td>Function that takes one parameter, the user’s input and returns an element.</td> <td>Generates <code><div></code> with class <code>awesomplete</code></td> </tr> <tr> <td><code>item</code></td> <td>Controls how list items are generated.</td> <td>Function that takes two parameters, the first one being the suggestion text and the second one the user’s input and returns a list item.</td> <td>Generates list items with the user’s input highlighted via <code><mark></code>.</td> </tr> <tr> <td><code>replace</code></td> <td>Controls how the user’s selection replaces the user’s input. For example, this is useful if you want the selection to only partially replace the user’s input.</td> <td>Function that takes one parameter, the text of the selected option, and is responsible for replacing the current input value with it. </td> <td><pre class="language-javascript"><code>function (text) { this.input.value = text; }</code></pre></td> </tr> <tr> <td><code>data</code></td> <td>Controls suggestions' <code>label</code> and <code>value</code>. This is useful if you have list items in custom format, or want to change list items based on user's input.</td> <td>Function that takes two parameters, the first one being the original list item and the second a string with the user’s input and returns a list item in one of supported by default formats: <ul> <li><code>"JavaScript"</code></li> <li><code>{ label: "JavaScript", value: "JS" }</code></li> <li><code>[ "JavaScript", "JS" ]</code></li> </ul> To <strong>use objects without <code>label</code> or <code>value</code> properties</strong>, e.g. <code>name</code> and <code>id</code> instead, you can do this: <pre class="language-javascript"><code>data: function (item, input) { return { label: item.name, value: item.id }; }</code></pre> You can <strong>use any object for <code>label</code> and <code>value</code></strong> and it will be converted to String where necessary: <pre class="language-javascript"><code>list: [ new Date("2015-01-01"), ... ] </code></pre> Original list items as Date objects will be accessible in <code>filter</code>, <code>sort</code>, <code>item</code> and <code>replace</code> functions, but by default we'll just see Date objects converted to strings in autocompleter and the same value will be inserted to the input. <br /> We can also <strong>generate list items based on user's input</strong>. See E-mail autocomplete example in <a href="#advanced-examples">Advanced Examples</a> section. </td> <td><code class="language-javascript">Awesomplete.DATA</code>: Identity function which just returns the original list item.</td> </tr> </tbody> </table> </section> <section id="events"> <h1>Events</h1> <p>Custom events are thrown in several places and are often cancellable. To avoid conflicts, all custom events are prefixed with <code>awesomplete-</code>.</p> <table> <thead> <tr> <th>Name</th> <th>Description</th> <th>event.preventDefault()?</th> </tr> </thead> <tbody> <tr> <td><code>awesomplete-select</code></td> <td>The user has made a selection (either via pressing enter or clicking on an item), but it has not been applied yet. Callback will be passed an object with <code>text</code> (selected suggestion), <code>origin</code> (DOM element) properties and <code>originalEvent</code> the original triggering DOM event.</td> <td>Yes. The selection will not be applied and the popup will not close.</td> </tr> <tr> <td><code>awesomplete-selectcomplete</code></td> <td>The user has made a selection (either via pressing enter or clicking on an item), and it has been applied. Callback will be passed an object with a <code>text</code> property containing the selected suggestion and <code>originalEvent</code> the original triggering DOM event.</td> <td>No</td> </tr> <tr> <td><code>awesomplete-open</code></td> <td>The popup just appeared.</td> <td>No</td> </tr> <tr> <td><code>awesomplete-close</code></td> <td>The popup just closed. Callback will be passed an object with a <code>reason</code> property that indicates why the event was fired. Reasons include <code>"blur"</code>, <code>"esc"</code>, <code>"submit"</code>, <code>"select"</code>, and <code>"nomatches"</code>.</td> <td>No</td> </tr> <tr> <td><code>awesomplete-highlight</code></td> <td>The highlighted item just changed (in response to pressing an arrow key or via an API call). Callback will be passed an object with a <code>text</code> property containing the highlighted suggestion.</td> <td>No</td> </tr> </tbody> </table> </section> <section id="api"> <h1>API</h1> <p>There are several methods on every Awesomplete instance that you can call to customize behavior:</p> <table> <thead> <tr> <th>Method</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>open()</code></td> <td>Opens the popup.</td> </tr> <tr> <td><code>close()</code></td> <td>Closes the popup.</td> </tr> <tr> <td><code>next()</code></td> <td>Highlights the next item in the popup.</td> </tr> <tr> <td><code>previous()</code></td> <td>Highlights the previous item in the popup.</td> </tr> <tr> <td><code>goto(i)</code></td> <td>Highlights the item with index <code>i</code> in the popup (<code>-1</code> to deselect all). Avoid using this directly and try to use <code>next()</code> or <code>previous()</code> instead when possible.</td> </tr> <tr> <td><code>select()</code></td> <td>Selects the currently highlighted item, replaces the text field’s value with it and closes the popup.</td> </tr> <tr> <td><code>evaluate()</code></td> <td>Evaluates the current state of the widget and regenerates the list of suggestions or closes the popup if none are available. You need to call it if you dynamically set <code>list</code> while the popup is open.</td> </tr> <tr> <td><code>destroy()</code></td> <td>Clean up and remove the instance from the input. The container is only removed if it wasn't manually set but created by Awesomplete.</td> </tr> </tbody> </table> </section> <section id="advanced-examples"> <h1>Advanced Examples</h1> <p>These examples show how powerful Awesomplete’s minimal API can be.</p> <section id="email"> <h2>E-mail autocomplete</h2> <label>Type an email: <input type="email"></label> <pre class="language-markup"><code><input type="email" /></code></pre> <pre class="language-javascript"><code><script>new Awesomplete('input[type="email"]', { list: ["aol.com", "att.net", "comcast.net", "facebook.com", "gmail.com", "gmx.com", "googlemail.com", "google.com", "hotmail.com", "hotmail.co.uk", "mac.com", "me.com", "mail.com", "msn.com", "live.com", "sbcglobal.net", "verizon.net", "yahoo.com", "yahoo.co.uk"], data: function (text, input) { return input.slice(0, input.indexOf("@")) + "@" + text; }, filter: Awesomplete.FILTER_STARTSWITH });</script></code></pre> </section> <section id="multiple-values"> <h2>Multiple values</h2> <label>Tags (comma separated): <input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" data-multiple data-minchars="1" /></label> <pre class="language-markup"><code><input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" data-multiple /></code></pre> <pre class="language-javascript"><code><script>new Awesomplete('input[data-multiple]', { filter: function(text, input) { return Awesomplete.FILTER_CONTAINS(text, input.match(/[^,]*$/)[0]); }, item: function(text, input) { return Awesomplete.ITEM(text, input.match(/[^,]*$/)[0]); }, replace: function(text) { var before = this.input.value.match(/^.+,\s*|/)[0]; this.input.value = before + text + ", "; } });</script></code></pre> </section> <section id="ajax-example"> <h2>Ajax example <small>(restcountries.eu api)</small></h2> <label class="">Select French speaking country <input type="text"></label> <pre class="language-javascript"><code><script>var ajax = new XMLHttpRequest(); ajax.open("GET", "https://restcountries.eu/rest/v1/lang/fr", true); ajax.onload = function() { var list = JSON.parse(ajax.responseText).map(function(i) { return i.name; }); new Awesomplete(document.querySelector("#ajax-example input"),{ list: list }); }; ajax.send();</script></code></pre> </section> <section id="ajax-example"> <h2>Custom list example <small>(based on user input)</small></h2> <pre class="language-markup"><code><input id="query" class="awesomplete" /></code></pre> <pre class="language-javascript"><code><script> const queryInput = document.querySelector("#query"); const awesomplete = new Awesomplete(queryInput, { filter: () => { // We will provide a list that is already filtered ... return true; }, sort: false, // ... and sorted. list: [] }); queryInput.addEventListener("input", (event) => { const inputText = event.target.value; // Process inputText as you want, e.g. make an API request. awesomplete.list = ["my"+inputText, "custom"+inputText, "list"+inputText]; awesomplete.evaluate(); }); </script></code></pre> </section> <section id="combobox"> <h2>Combobox dropdown</h2> <label>Type or click dropdown: <input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" class="dropdown-input" /><button class="dropdown-btn" type="button"><span class="caret"></span></button></label> <pre class="language-markup"><code><input data-list="CSS, JavaScript, HTML, SVG, ARIA, MathML" class="dropdown-input" /></code></pre> <pre class="language-javascript"><code><script>var comboplete = new Awesomplete('input.dropdown-input', { minChars: 0, }); Awesomplete.$('.dropdown-btn').addEventListener("click", function() { if (comboplete.ul.childNodes.length === 0) { comboplete.minChars = 0; comboplete.evaluate(); } else if (comboplete.ul.hasAttribute('hidden')) { comboplete.open(); } else { comboplete.close(); } });</script></code></pre> </section> <section id="download"> <h1>Download!</h1> <ul> <li><strong><a href="https://github.com/LeaVerou/awesomplete/archive/gh-pages.zip">Download everything as a zip file</a></strong></li> <li><a href="https://github.com/LeaVerou/awesomplete">Fork me on Github</a></li> <li><a href="https://github.com/LeaVerou/awesomplete/issues/new">File a bug</a> </li> <li><a href="https://github.com/LeaVerou/awesomplete/issues/new">Suggest a feature</a> </li> <li><a href="https://github.com/LeaVerou/awesomplete/blob/gh-pages/LICENSE">License: MIT license</a></li> </ul> <p><strong>Pull requests are very welcome</strong>, as long as you maintain the code style and ask before adding tons of LOCs to the codebase!</p> </section> <footer>Made with &hearts; by <a href="http://lea.verou.me">Lea Verou</a> • <a href="http://lea.verou.me/2015/02/awesomplete-2kb-autocomplete-with-zero-dependencies">Read the blog post</a> • <a href="http://shop.oreilly.com/product/0636920031123.do">Buy my book!</a> </footer> <script src="prism/prism.js" defer></script> <iframe src="https://ghbtns.com/github-btn.html?user=leaverou&repo=awesomplete&type=watch&count=true&size=large" height="30" width="170" frameborder="0" scrolling="0" style="width:170px; height: 30px;" allowTransparency="true" class="github-star"></iframe> <a href="https://twitter.com/share" class="twitter-share-button" data-via="LeaVerou" data-size="large">Tweet</a> <script async src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=leaveroume" id="_carbonads_js"></script> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-25106441-4', 'auto'); ga('send', 'pageview'); </script> </body> </html>