<blockquote>
<p><strong>⚠️ Deprecation notice</strong></p>
<p><a href="https://www.npmjs.com/package/autocomplete.js">Autocomplete.js (v0.x)</a> is deprecated and no longer supported. Please use <a href="https://github.com/algolia/autocomplete#readme">Autocomplete</a> instead.
To upgrade from v0.x, please follow our <a href="https://www.algolia.com/doc/ui-libraries/autocomplete/guides/upgrading/">upgrade guide</a>.</p>
</blockquote>
<h1 id="id-autocompletejs">Autocomplete.js</h1>
<p>This JavaScript library adds a fast and fully-featured auto-completion menu to your search box displaying results &quot;as you type&quot;. It can easily be combined with Algolia&#39;s realtime search engine. The library is available as a jQuery plugin, an Angular.js directive or a standalone library.</p>
<p><a href="http://travis-ci.org/algolia/autocomplete.js"><img src="https://travis-ci.org/algolia/algoliasearch-client-node.svg?branch=master" alt="build status"></a>
<a href="http://badge.fury.io/js/autocomplete.js"><img src="https://badge.fury.io/js/autocomplete.js.svg" alt="NPM version"></a>
<a href="https://coveralls.io/r/algolia/autocomplete.js?branch=master"><img src="https://coveralls.io/repos/algolia/autocomplete.js/badge.svg?branch=master" alt="Coverage Status"></a>
<a href="https://www.jsdelivr.com/package/npm/autocomplete.js"><img src="https://data.jsdelivr.com/v1/package/npm/autocomplete.js/badge?style=rounded" alt="jsDelivr Hits"></a>
<img src="https://img.shields.io/badge/jQuery-OK-blue.svg" alt="jQuery">
<img src="https://img.shields.io/badge/Zepto.js-OK-blue.svg" alt="Zepto.js">
<img src="https://img.shields.io/badge/Angular.js-OK-blue.svg" alt="Angular.js">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a></p>
<p><a href="https://saucelabs.com/u/opensauce-algolia"><img src="https://saucelabs.com/browser-matrix/opensauce-algolia.svg" alt="Browser tests"></a></p>
<h2 id="id-table-of-contents">Table of Contents</h2>
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


<ul>
<li><a href="#features">Features</a></li>
<li><a href="#installation">Installation</a><ul>
<li><a href="#jsdelivr">jsDelivr</a></li>
<li><a href="#cdnjs">cdnjs</a></li>
<li><a href="#npm">npm</a></li>
<li><a href="#bower">Bower</a></li>
<li><a href="#source-dist">Source dist/</a></li>
<li><a href="#browserify">Browserify</a></li>
</ul>
</li>
<li><a href="#usage">Usage</a><ul>
<li><a href="#standalone">Standalone</a></li>
<li><a href="#jquery">jQuery</a></li>
<li><a href="#angularjs">Angular.JS</a></li>
</ul>
</li>
<li><a href="#look-and-feel">Look and Feel</a></li>
<li><a href="#global-options">Global Options</a></li>
<li><a href="#datasets">Datasets</a></li>
<li><a href="#sources">Sources</a><ul>
<li><a href="#hits">Hits</a></li>
<li><a href="#popularin-aka-xxxxx-in-yyyyy">PopularIn (aka &quot;xxxxx in yyyyy&quot;)</a></li>
<li><a href="#custom-source">Custom source</a></li>
</ul>
</li>
<li><a href="#security">Security</a><ul>
<li><a href="#user-generated-data-protecting-against-xss">User-generated data: protecting against XSS</a></li>
</ul>
</li>
<li><a href="#faq">FAQ</a><ul>
<li><a href="#how-can-i-control-click-on-results-and-have-them-open-in-a-new-tab">How can I <code>Control</code>-click on results and have them open in a new tab?</a></li>
</ul>
</li>
<li><a href="#events">Events</a></li>
<li><a href="#api">API</a><ul>
<li><a href="#jquery-1">jQuery</a></li>
<li><a href="#standalone-1">Standalone</a></li>
</ul>
</li>
<li><a href="#contributing--releasing">Contributing &amp; releasing</a></li>
<li><a href="#credits">Credits</a></li>
</ul>
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<h2 id="id-features">Features</h2>
<ul>
<li>Displays suggestions to end-users as they type</li>
<li>Shows top suggestion as a hint (i.e. background text)</li>
<li>Supports custom templates to allow for UI flexibility</li>
<li>Works well with RTL languages and input method editors</li>
<li>Triggers custom events</li>
</ul>
<h2 id="id-installation">Installation</h2>
<p>The <code>autocomplete.js</code> library must be included <strong>after</strong> jQuery, Zepto or Angular.js (with jQuery). Else, it will use the embedded Zepto.</p>
<h3 id="id-jsdelivr">jsDelivr</h3>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-comment">&lt;!-- OR --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-comment">&lt;!-- OR --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<h3 id="id-cdnjs">cdnjs</h3>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/&lt;VERSION&gt;/autocomplete.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-comment">&lt;!-- OR --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/&lt;VERSION&gt;/autocomplete.jquery.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-comment">&lt;!-- OR --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/&lt;VERSION&gt;/autocomplete.angular.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<h3 id="id-npm">npm</h3>
<pre><code class="hljs language-sh">npm install --save autocomplete.js
</code></pre>
<h3 id="id-bower">Bower</h3>
<pre><code class="hljs language-sh">bower install algolia-autocomplete.js -S
</code></pre>
<h3 id="id-source-dist">Source dist/</h3>
<p>You can find the built version in <a href="https://github.com/algolia/autocomplete.js/tree/master/dist">dist/</a>.</p>
<h3 id="id-browserify">Browserify</h3>
<p>You can require it and use <a href="http://browserify.org/">Browserify</a>:</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> autocomplete = <span class="hljs-built_in">require</span>(<span class="hljs-string">&#x27;autocomplete.js&#x27;</span>);
</code></pre>
<h2 id="id-usage">Usage</h2>
<h3 id="id-standalone">Standalone</h3>
<ol>
<li>Include <code>autocomplete.min.js</code></li>
<li>Initialize the auto-completion menu calling the <code>autocomplete</code> function</li>
</ol>
<p> <strong>Warning</strong>: <code>autocomplete.js</code> is not compatible with the latest version algoliasearch v4 out of the box, but you can create a compatibility source by yourself like this:</p>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;text&quot;</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;search-input&quot;</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;Search unicorns...&quot;</span> /&gt;</span>

<span class="hljs-comment">&lt;!-- [ ... ] --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/npm/algoliasearch@4/dist/algoliasearch.umd.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="language-javascript">
  <span class="hljs-keyword">var</span> client = <span class="hljs-title function_">algoliasearch</span>(<span class="hljs-string">&#x27;YourApplicationID&#x27;</span>, <span class="hljs-string">&#x27;YourSearchOnlyAPIKey&#x27;</span>);
  <span class="hljs-keyword">var</span> index = client.<span class="hljs-title function_">initIndex</span>(<span class="hljs-string">&#x27;YourIndex&#x27;</span>);

  <span class="hljs-keyword">function</span> <span class="hljs-title function_">newHitsSource</span>(<span class="hljs-params">index, params</span>) {
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">doSearch</span>(<span class="hljs-params">query, cb</span>) {
      index
        .<span class="hljs-title function_">search</span>(query, params)
        .<span class="hljs-title function_">then</span>(<span class="hljs-keyword">function</span>(<span class="hljs-params">res</span>) {
          <span class="hljs-title function_">cb</span>(res.<span class="hljs-property">hits</span>, res);
        })
        .<span class="hljs-keyword">catch</span>(<span class="hljs-keyword">function</span>(<span class="hljs-params">err</span>) {
          <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err);
          <span class="hljs-title function_">cb</span>([]);
        });
    };
  }

  <span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;#search-input&#x27;</span>, { <span class="hljs-attr">hint</span>: <span class="hljs-literal">false</span> }, [
    {
      <span class="hljs-attr">source</span>: <span class="hljs-title function_">newHitsSource</span>(index, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> }),
      <span class="hljs-attr">displayKey</span>: <span class="hljs-string">&#x27;my_attribute&#x27;</span>,
      <span class="hljs-attr">templates</span>: {
        <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
          <span class="hljs-keyword">return</span> suggestion.<span class="hljs-property">_highlightResult</span>.<span class="hljs-property">my_attribute</span>.<span class="hljs-property">value</span>;
        }
      }
    }
  ]).<span class="hljs-title function_">on</span>(<span class="hljs-string">&#x27;autocomplete:selected&#x27;</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params">event, suggestion, dataset, context</span>) {
    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event, suggestion, dataset, context);
  });
</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<h3 id="id-jquery">jQuery</h3>
<ol>
<li>Include <code>autocomplete.jquery.min.js</code> after including <code>jQuery</code></li>
<li>Initialize the auto-completion menu calling the <code>autocomplete</code> jQuery plugin</li>
</ol>
<p> <strong>Warning</strong>: <code>autocomplete.js</code> is not compatible with the latest version algoliasearch v4, therefore we highly recommend you use algoliasearch v3 as specified in the code snippet below.</p>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;text&quot;</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;search-input&quot;</span> /&gt;</span>

<span class="hljs-comment">&lt;!-- [ ... ] --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="language-javascript">
  <span class="hljs-keyword">var</span> client = <span class="hljs-title function_">algoliasearch</span>(<span class="hljs-string">&#x27;YourApplicationID&#x27;</span>, <span class="hljs-string">&#x27;YourSearchOnlyAPIKey&#x27;</span>)
  <span class="hljs-keyword">var</span> index = client.<span class="hljs-title function_">initIndex</span>(<span class="hljs-string">&#x27;YourIndex&#x27;</span>);
  $(<span class="hljs-string">&#x27;#search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>({ <span class="hljs-attr">hint</span>: <span class="hljs-literal">false</span> }, [
    {
      <span class="hljs-attr">source</span>: $.fn.<span class="hljs-property">autocomplete</span>.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> }),
      <span class="hljs-attr">displayKey</span>: <span class="hljs-string">&#x27;my_attribute&#x27;</span>,
      <span class="hljs-attr">templates</span>: {
        <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
          <span class="hljs-keyword">return</span> suggestion.<span class="hljs-property">_highlightResult</span>.<span class="hljs-property">my_attribute</span>.<span class="hljs-property">value</span>;
        }
      }
    }
  ]).<span class="hljs-title function_">on</span>(<span class="hljs-string">&#x27;autocomplete:selected&#x27;</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params">event, suggestion, dataset, context</span>) {
    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event, suggestion, dataset, context);
  });
</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<h3 id="id-angularjs">Angular.JS</h3>
<ol>
<li>Include <code>autocomplete.angular.min.js</code> after including <code>jQuery</code> &amp; <code>Angular.js</code></li>
<li>Inject the <code>algolia.autocomplete</code> module</li>
<li>Add the <code>autocomplete</code>, <code>aa-datasets</code> and the optional <code>aa-options</code> attribute to your search bar</li>
</ol>
<p> <strong>Warning</strong>: <code>autocomplete.js</code> is not compatible with the latest version algoliasearch v4, therefore we highly recommend you use algoliasearch v3 as specified in the code snippet below.</p>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">ng-controller</span>=<span class="hljs-string">&quot;yourController&quot;</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;text&quot;</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;search-input&quot;</span> <span class="hljs-attr">autocomplete</span> <span class="hljs-attr">aa-datasets</span>=<span class="hljs-string">&quot;getDatasets()&quot;</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>

<span class="hljs-comment">&lt;!-- [ include jQuery + Angular.js ] --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">&quot;https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="language-javascript">
  angular.<span class="hljs-title function_">module</span>(<span class="hljs-string">&#x27;myApp&#x27;</span>, [<span class="hljs-string">&#x27;algoliasearch&#x27;</span>, <span class="hljs-string">&#x27;algolia.autocomplete&#x27;</span>])
    .<span class="hljs-title function_">controller</span>(<span class="hljs-string">&#x27;yourController&#x27;</span>, [<span class="hljs-string">&#x27;$scope&#x27;</span>, <span class="hljs-string">&#x27;algolia&#x27;</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params">$scope, algolia</span>) {
      <span class="hljs-keyword">var</span> client = algolia.<span class="hljs-title class_">Client</span>(<span class="hljs-string">&#x27;YourApplicationID&#x27;</span>, <span class="hljs-string">&#x27;YourSearchOnlyAPIKey&#x27;</span>);
      <span class="hljs-keyword">var</span> index = client.<span class="hljs-title function_">initIndex</span>(<span class="hljs-string">&#x27;YourIndex&#x27;</span>);

      $scope.<span class="hljs-property">getDatasets</span> = <span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) {
        <span class="hljs-keyword">return</span> {
          <span class="hljs-attr">source</span>: algolia.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> }),
          <span class="hljs-attr">displayKey</span>: <span class="hljs-string">&#x27;my_attribute&#x27;</span>,
          <span class="hljs-attr">templates</span>: {
            <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
              <span class="hljs-keyword">return</span> suggestion.<span class="hljs-property">_highlightResult</span>.<span class="hljs-property">my_attribute</span>.<span class="hljs-property">value</span>;
            }
          }
        };
      };

      $scope.$on(<span class="hljs-string">&#x27;autocomplete:selected&#x27;</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params">event, suggestion, dataset</span>) {
        <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(event, suggestion, dataset, context);
      });
    }]);
</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<p><strong>Note:</strong> You need to rely on <code>jQuery</code>, the lite version embedded in Angular.js won&#39;t work.</p>
<h2 id="id-look-and-feel">Look and Feel</h2>
<p>Below is a faux mustache template describing the DOM structure of an autocomplete
dropdown menu. Keep in mind that <code>header</code>, <code>footer</code>, <code>suggestion</code>, and <code>empty</code>
come from the provided templates detailed <a href="#datasets">here</a>.</p>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-dropdown-menu{{#datasets}} aa-{{&#x27;with&#x27; or &#x27;without&#x27;}}-{{name}}{{/datasets}}&quot;</span>&gt;</span>
  {{#datasets}}
    <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-dataset-{{name}}&quot;</span>&gt;</span>
      {{{header}}}
      <span class="hljs-tag">&lt;<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-suggestions&quot;</span>&gt;</span>
        {{#suggestions}}
          <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-suggestion&quot;</span>&gt;</span>{{{suggestion}}}<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
        {{/suggestions}}
        {{^suggestions}}
          {{{empty}}}
        {{/suggestions}}
      <span class="hljs-tag">&lt;/<span class="hljs-name">span</span>&gt;</span>
      {{{footer}}}
    <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
  {{/datasets}}
  {{empty}}
<span class="hljs-tag">&lt;/<span class="hljs-name">span</span>&gt;</span>
</code></pre>
<p>When an end-user mouses or keys over a <code>.aa-suggestion</code>, the class <code>aa-cursor</code> will be added to it. You can use this class as a hook for styling the &quot;under cursor&quot; state of suggestions.</p>
<p>Add the following CSS rules to add a default style:</p>
<pre><code class="hljs language-css">.algolia-autocomplete {
  width: 100%;
}
.algolia-autocomplete .aa-input, .algolia-autocomplete .aa-hint {
  width: 100%;
}
.algolia-autocomplete .aa-hint {
  color: <span class="hljs-comment">#999;</span>
}
.algolia-autocomplete .aa-dropdown-menu {
  width: 100%;
  background-color: <span class="hljs-comment">#fff;</span>
  border: 1px solid <span class="hljs-comment">#999;</span>
  border-top: none;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion {
  cursor: pointer;
  padding: 5px 4px;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion.aa-cursor {
  background-color: <span class="hljs-comment">#B2D7FF;</span>
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion em {
  font-weight: bold;
  font-style: normal;
}
</code></pre>
<p>Here is what the <a href="https://github.com/algolia/autocomplete.js/tree/master/examples">basic example</a> looks like:</p>
<p><img src="./examples/basic.gif" alt="Basic example"></p>
<h2 id="id-global-options">Global Options</h2>
<p>When initializing an autocomplete, there are a number of global options you can configure.</p>
<ul>
<li><p><code>autoselect</code> – If <code>true</code>, the first rendered suggestion in the dropdown will automatically have the <code>cursor</code> class, and pressing <code>&lt;ENTER&gt;</code> will select it.</p>
</li>
<li><p><code>autoselectOnBlur</code> – If <code>true</code>, when the input is blurred, the first rendered suggestion in the dropdown will automatically have the <code>cursor</code> class, and pressing <code>&lt;ENTER&gt;</code> will select it. This option should be used on mobile, see <a href="https://github.com/algolia/autocomplete.js/issues/113">#113</a></p>
</li>
<li><p><code>tabAutocomplete</code> – If <code>true</code>, pressing tab will select the first rendered suggestion in the dropdown. Defaults to <code>true</code>.</p>
</li>
<li><p><code>hint</code> – If <code>false</code>, the autocomplete will not show a hint. Defaults to <code>true</code>.</p>
</li>
<li><p><code>debug</code> – If <code>true</code>, the autocomplete will not close on <code>blur</code>. Defaults to <code>false</code>.</p>
</li>
<li><p><code>clearOnSelected</code> – If <code>true</code>, the autocomplete will empty the search box when a suggestion is selected. This is useful if you want to use this as a way to input tags using the <code>selected</code> event.</p>
</li>
<li><p><code>openOnFocus</code> – If <code>true</code>, the dropdown menu will open when the input is focused. Defaults to <code>false</code>.</p>
</li>
<li><p><code>appendTo</code> – If set with a DOM selector, doesn&#39;t wrap the input and appends the wrapper and dropdown menu to the first DOM element matching the selector. It automatically positions the wrapper under the input, and sets it to the same width as the input. Can&#39;t be used with <code>hint: true</code>, because <code>hint</code> requires the wrapper around the input.</p>
</li>
<li><p><code>dropdownMenuContainer</code> – If set with a DOM selector, it overrides the container of the dropdown menu.</p>
</li>
<li><p><code>templates</code> – An optional hash overriding the default templates.</p>
<ul>
<li><code>dropdownMenu</code> – the dropdown menu template. The template should include all <em>dataset</em> placeholders.</li>
<li><code>header</code> – the header to prepend to the dropdown menu</li>
<li><code>footer</code> – the footer to append to the dropdown menu</li>
<li><code>empty</code> – the template to display when none of the datasets are returning results. The templating function
is called with a context containing the underlying <code>query</code>.</li>
</ul>
</li>
<li><p><code>cssClasses</code> – An optional hash overriding the default css classes.</p>
<ul>
<li><code>root</code> – the root classes. Defaults to <code>algolia-autocomplete</code>.</li>
<li><code>prefix</code> – the CSS class prefix of all nested elements. Defaults to <code>aa</code>.</li>
<li><code>noPrefix</code> - set this to true if you wish to not use any prefix. Without this option, all nested elements classes will have a leading dash. Defaults to <code>false</code>.</li>
<li><code>dropdownMenu</code> – the dropdown menu CSS class. Defaults to <code>dropdown-menu</code>.</li>
<li><code>input</code> – the input CSS class. Defaults to <code>input</code>.</li>
<li><code>hint</code> – the hint CSS class. Defaults to <code>hint</code>.</li>
<li><code>suggestions</code> – the suggestions list CSS class. Defaults to <code>suggestions</code>.</li>
<li><code>suggestion</code> – the suggestion wrapper CSS class. Defaults to <code>suggestion</code>.</li>
<li><code>cursor</code> – the cursor CSS class. Defaults to <code>cursor</code>.</li>
<li><code>dataset</code> – the dataset CSS class. Defaults to <code>dataset</code>.</li>
<li><code>empty</code> – the empty CSS class. Defaults to <code>empty</code>.</li>
</ul>
</li>
<li><p><code>keyboardShortcuts</code> - Array of shortcut that will focus the input. For example if you want to bind <code>s</code> and <code>/</code>
 you can specify: <code>keyboardShortcuts: [&#39;s&#39;, &#39;/&#39;]</code></p>
</li>
<li><p><code>ariaLabel</code> - An optional string that will populate the <code>aria-label</code> attribute.</p>
</li>
</ul>
<pre><code class="hljs language-html"><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;text/template&quot;</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;my-custom-menu-template&quot;</span>&gt;</span><span class="language-handlebars"><span class="language-xml">
  <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;my-custom-menu&quot;</span>&gt;</span>
    <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;row&quot;</span>&gt;</span>
      <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;col-sm-6&quot;</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-dataset-d1&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
      <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
      <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;col-sm-6&quot;</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-dataset-d2&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;aa-dataset-d3&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
      <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
    <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
  <span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
</span></span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">style</span>&gt;</span><span class="language-css">
<span class="hljs-selector-tag">body</span> {
    <span class="hljs-attribute">font-family</span>: -apple-system, sans-serif;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> {
  <span class="hljs-attribute">width</span>: <span class="hljs-number">100%</span>;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-input</span>, <span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-hint</span> {
  <span class="hljs-attribute">width</span>: <span class="hljs-number">100%</span>;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-hint</span> {
  <span class="hljs-attribute">color</span>: <span class="hljs-number">#999</span>;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-dropdown-menu</span> {
  <span class="hljs-attribute">width</span>: <span class="hljs-number">100%</span>;
  <span class="hljs-attribute">background-color</span>: <span class="hljs-number">#fff</span>;
  <span class="hljs-attribute">border</span>: <span class="hljs-number">1px</span> solid <span class="hljs-number">#999</span>;
  <span class="hljs-attribute">border-top</span>: none;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-dropdown-menu</span> <span class="hljs-selector-class">.aa-suggestion</span> {
  <span class="hljs-attribute">cursor</span>: pointer;
  <span class="hljs-attribute">padding</span>: <span class="hljs-number">5px</span> <span class="hljs-number">4px</span>;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-dropdown-menu</span> <span class="hljs-selector-class">.aa-suggestion</span><span class="hljs-selector-class">.aa-cursor</span> {
  <span class="hljs-attribute">background-color</span>: <span class="hljs-number">#B2D7FF</span>;
}
<span class="hljs-selector-class">.algolia-autocomplete</span> <span class="hljs-selector-class">.aa-dropdown-menu</span> <span class="hljs-selector-class">.aa-suggestion</span> <span class="hljs-selector-tag">em</span> {
  <span class="hljs-attribute">font-weight</span>: bold;
  <span class="hljs-attribute">font-style</span>: normal;
}

<span class="hljs-selector-class">.branding</span> {
<span class="hljs-attribute">font-size</span>: <span class="hljs-number">1.3em</span>;
<span class="hljs-attribute">margin</span>: <span class="hljs-number">0.5em</span> <span class="hljs-number">0.2em</span>;
}

<span class="hljs-selector-class">.branding</span> <span class="hljs-selector-tag">img</span> {
    <span class="hljs-attribute">height</span>: <span class="hljs-number">1.3em</span>;
    <span class="hljs-attribute">margin-bottom</span>: - <span class="hljs-number">0.3em</span>;
}
</span><span class="hljs-tag">&lt;/<span class="hljs-name">style</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="language-javascript">
  $(<span class="hljs-string">&#x27;#search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(
    {
      <span class="hljs-attr">templates</span>: {
        <span class="hljs-attr">dropdownMenu</span>: <span class="hljs-string">&#x27;#my-custom-menu-template&#x27;</span>,
        <span class="hljs-attr">footer</span>: <span class="hljs-string">&#x27;&lt;div class=&quot;branding&quot;&gt;Powered by &lt;img src=&quot;https://www.algolia.com/static_assets/images/press/downloads/algolia-logo-light.svg&quot; /&gt;&lt;/div&gt;&#x27;</span>
      }
    },
    [
      {
        <span class="hljs-attr">source</span>: $.fn.<span class="hljs-property">autocomplete</span>.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index1, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> }),
        <span class="hljs-attr">name</span>: <span class="hljs-string">&#x27;d1&#x27;</span>,
        <span class="hljs-attr">templates</span>: {
          <span class="hljs-attr">header</span>: <span class="hljs-string">&#x27;&lt;h4&gt;List 1&lt;/h4&gt;&#x27;</span>,
          <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
            <span class="hljs-comment">// FIXME</span>
          }
        }
      },
      {
        <span class="hljs-attr">source</span>: $.fn.<span class="hljs-property">autocomplete</span>.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index2, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">2</span> }),
        <span class="hljs-attr">name</span>: <span class="hljs-string">&#x27;d2&#x27;</span>,
        <span class="hljs-attr">templates</span>: {
          <span class="hljs-attr">header</span>: <span class="hljs-string">&#x27;&lt;h4&gt;List 2&lt;/h4&gt;&#x27;</span>,
          <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
            <span class="hljs-comment">// FIXME</span>
          }
        }
      },
      {
        <span class="hljs-attr">source</span>: $.fn.<span class="hljs-property">autocomplete</span>.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index3, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">2</span> }),
        <span class="hljs-attr">name</span>: <span class="hljs-string">&#x27;d3&#x27;</span>,
        <span class="hljs-attr">templates</span>: {
          <span class="hljs-attr">header</span>: <span class="hljs-string">&#x27;&lt;h4&gt;List 3&lt;/h4&gt;&#x27;</span>,
          <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion, answer</span>) {
            <span class="hljs-comment">// FIXME</span>
          }
        }
      }
    ]
  );
</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span>
</code></pre>
<ul>
<li><p><code>minLength</code> – The minimum character length needed before suggestions start
getting rendered. Defaults to <code>1</code>.</p>
</li>
<li><p><code>autoWidth</code> – This option allow you to control the width of autocomplete wrapper. When <code>false</code> the autocomplete wrapper will not have the width style attribute and you are be able to put your specific width property in your css to control the wrapper. Default value is <code>true</code>.</p>
</li>
</ul>
<p>One scenario for use this option. e.g. You have a <code>max-width</code> css attribute in your <code>autocomplete-dropdown-menu</code> and you need to width grows until fill the <code>max-width</code>. In this scenario you put a <code>width: auto</code> in your autocomplete wrapper css class and the <code>max-width</code> in your autocomplete dropdown class and all done.</p>
<h2 id="id-datasets">Datasets</h2>
<p>An autocomplete is composed of one or more datasets. When an end-user modifies the
value of the underlying input, each dataset will attempt to render suggestions for the
new value.</p>
<p>Datasets can be configured using the following options.</p>
<ul>
<li><p><code>source</code> – The backing data source for suggestions. Expected to be a function
with the signature <code>(query, cb)</code>. It is expected that the function will
compute the suggestion set (i.e. an array of JavaScript objects) for <code>query</code>
and then invoke <code>cb</code> with said set. <code>cb</code> can be invoked synchronously or
asynchronously.</p>
</li>
<li><p><code>name</code> – The name of the dataset. This will be appended to <code>tt-dataset-</code> to
form the class name of the containing DOM element.  Must only consist of
underscores, dashes, letters (<code>a-z</code>), and numbers. Defaults to a random
number.</p>
</li>
<li><p><code>displayKey</code> – For a given suggestion object, determines the string
representation of it. This will be used when setting the value of the input
control after a suggestion is selected. Can be either a key string or a
function that transforms a suggestion object into a string. Defaults to
<code>value</code>.
Example function usage: <code>displayKey: function(suggestion) { return suggestion.nickname || suggestion.firstName }</code></p>
</li>
<li><p><code>templates</code> – A hash of templates to be used when rendering the dataset. Note
a precompiled template is a function that takes a JavaScript object as its
first argument and returns a HTML string.</p>
<ul>
<li><p><code>empty</code> – Rendered when <code>0</code> suggestions are available for the given query.
Can be either a HTML string or a precompiled template. The templating function
is called with a context containing <code>query</code>, <code>isEmpty</code>, and any optional
arguments that may have been forwarded by the source:
<code>function emptyTemplate({ query, isEmpty }, [forwarded args])</code>.</p>
</li>
<li><p><code>footer</code> – Rendered at the bottom of the dataset. Can be either a HTML
string or a precompiled template. The templating function
is called with a context containing <code>query</code>, <code>isEmpty</code>, and any optional
arguments that may have been forwarded by the source:
<code>function footerTemplate({ query, isEmpty }, [forwarded args])</code>.</p>
</li>
<li><p><code>header</code> – Rendered at the top of the dataset. Can be either a HTML string
or a precompiled template. The templating function
is called with a context containing <code>query</code>, <code>isEmpty</code>, and any optional
arguments that may have been forwarded by the source:
<code>function headerTemplate({ query, isEmpty }, [forwarded args])</code>.</p>
</li>
<li><p><code>suggestion</code> – Used to render a single suggestion. The templating function
is called with the <code>suggestion</code>, and any optional arguments that may have
been forwarded by the source: <code>function suggestionTemplate(suggestion, [forwarded args])</code>.
Defaults to the value of <code>displayKey</code> wrapped in a <code>p</code> tag i.e. <code>&lt;p&gt;{{value}}&lt;/p&gt;</code>.</p>
</li>
</ul>
</li>
<li><p><code>debounce</code> – If set, will postpone the source execution until after <code>debounce</code> milliseconds
have elapsed since the last time it was invoked.</p>
</li>
<li><p><code>cache</code> - If set to <code>false</code>, subsequent identical queries will always execute the source function for suggestions. Defaults to <code>true</code>.</p>
</li>
</ul>
<h2 id="id-sources">Sources</h2>
<p>A few helpers are provided by default to ease the creation of Algolia-based sources.</p>
<h3 id="id-hits">Hits</h3>
<p>To build a source based on Algolia&#39;s <code>hits</code> array, just use:</p>
<pre><code class="hljs language-js">{
  <span class="hljs-attr">source</span>: autocomplete.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(indexObj, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">2</span> }),
  <span class="hljs-attr">templates</span>: {
    <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion, answer</span>) {
      <span class="hljs-comment">// FIXME</span>
    }
  }
}
</code></pre>
<h3 id="id-popularin-aka-xxxxx-in-yyyyy">PopularIn (aka &quot;xxxxx in yyyyy&quot;)</h3>
<p>To build an Amazon-like autocomplete menu, suggesting popular queries and for the most popular one displaying the associated categories, you can use the <code>popularIn</code> source:</p>
<pre><code class="hljs language-js">{
  <span class="hljs-attr">source</span>: autocomplete.<span class="hljs-property">sources</span>.<span class="hljs-title function_">popularIn</span>(popularQueriesIndexObj, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">3</span> }, {
    <span class="hljs-attr">source</span>: <span class="hljs-string">&#x27;sourceAttribute&#x27;</span>,           <span class="hljs-comment">// attribute of the `popularQueries` index use to query the `index` index</span>
    <span class="hljs-attr">index</span>: productsIndexObj,             <span class="hljs-comment">// targeted index</span>
    <span class="hljs-attr">facets</span>: <span class="hljs-string">&#x27;facetedCategoryAttribute&#x27;</span>,  <span class="hljs-comment">// facet used to enrich the most popular query</span>
    <span class="hljs-attr">maxValuesPerFacet</span>: <span class="hljs-number">3</span>                 <span class="hljs-comment">// maximum number of facets returned</span>
  }, {
    <span class="hljs-attr">includeAll</span>: <span class="hljs-literal">true</span>,                    <span class="hljs-comment">// should it include an extra &quot;All department&quot; suggestion</span>
    <span class="hljs-attr">allTitle</span>: <span class="hljs-string">&#x27;All departments&#x27;</span>          <span class="hljs-comment">// the included category label</span>
  }),
  <span class="hljs-attr">templates</span>: {
    <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion, answer</span>) {
      <span class="hljs-keyword">var</span> value = suggestion.<span class="hljs-property">sourceAttribute</span>;
      <span class="hljs-keyword">if</span> (suggestion.<span class="hljs-property">facet</span>) {
        <span class="hljs-comment">// this is the first suggestion</span>
        <span class="hljs-comment">// and it has been enriched with the matching facet</span>
        value += <span class="hljs-string">&#x27; in &#x27;</span> + suggestion.<span class="hljs-property">facet</span>.<span class="hljs-property">value</span> + <span class="hljs-string">&#x27; (&#x27;</span> + suggestion.<span class="hljs-property">facet</span>.<span class="hljs-property">count</span> + <span class="hljs-string">&#x27;)&#x27;</span>;
      }
      <span class="hljs-keyword">return</span> value;
    }
  }
}
</code></pre>
<h3 id="id-custom-source">Custom source</h3>
<p>The <code>source</code> options can also take a function. It enables you to have more control of the results returned by Algolia search. The function <code>function(query, callback)</code> takes 2 parameters</p>
<ul>
<li><code>query: String</code>: the text typed in the autocomplete</li>
<li><code>callback: Function</code>: the callback to call at the end of your processing with the array of suggestions</li>
</ul>
<pre><code class="hljs language-js"><span class="hljs-attr">source</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">query, callback</span>) {
  <span class="hljs-keyword">var</span> index = client.<span class="hljs-title function_">initIndex</span>(<span class="hljs-string">&#x27;myindex&#x27;</span>);
  index.<span class="hljs-title function_">search</span>(query, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">1</span>, <span class="hljs-attr">facetFilters</span>: <span class="hljs-string">&#x27;category:mycat&#x27;</span> }).<span class="hljs-title function_">then</span>(<span class="hljs-keyword">function</span>(<span class="hljs-params">answer</span>) {
    <span class="hljs-title function_">callback</span>(answer.<span class="hljs-property">hits</span>);
  }, <span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) {
    <span class="hljs-title function_">callback</span>([]);
  });
}
</code></pre>
<p>Or by reusing an existing source:</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> hitsSource = autocomplete.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> });

<span class="hljs-attr">source</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">query, callback</span>) {
  <span class="hljs-title function_">hitsSource</span>(query, <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestions</span>) {
    <span class="hljs-comment">// <span class="hljs-doctag">FIXME:</span> Do stuff with the array of returned suggestions</span>
    <span class="hljs-title function_">callback</span>(suggestions);
  });
}
</code></pre>
<h2 id="id-security">Security</h2>
<h3 id="id-user-generated-data-protecting-against-xss">User-generated data: protecting against XSS</h3>
<p>Malicious users may attempt to engineer XSS attacks by storing HTML/JS in their data. It is important that user-generated data be properly escaped before using it in an <em>autocomplete.js</em> template.</p>
<p>In order to easily do that, <em>autocomplete.js</em> provides you with a helper function escaping all HTML code but the highlighting tags:</p>
<pre><code class="hljs language-js">  <span class="hljs-attr">templates</span>: {
    <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
      <span class="hljs-keyword">var</span> val = suggestion.<span class="hljs-property">_highlightResult</span>.<span class="hljs-property">name</span>.<span class="hljs-property">value</span>;
      <span class="hljs-keyword">return</span> autocomplete.<span class="hljs-title function_">escapeHighlightedString</span>(val);
    }
  }
</code></pre>
<p>If you did specify custom highlighting pre/post tags, you can specify them as 2nd and 3rd parameter:</p>
<pre><code class="hljs language-js">  <span class="hljs-attr">templates</span>: {
    <span class="hljs-attr">suggestion</span>: <span class="hljs-keyword">function</span>(<span class="hljs-params">suggestion</span>) {
      <span class="hljs-keyword">var</span> val = suggestion.<span class="hljs-property">_highlightResult</span>.<span class="hljs-property">name</span>.<span class="hljs-property">value</span>;
      <span class="hljs-keyword">return</span> autocomplete.<span class="hljs-title function_">escapeHighlightedString</span>(val, <span class="hljs-string">&#x27;&lt;span class=&quot;highlighted&quot;&gt;&#x27;</span>, <span class="hljs-string">&#x27;&lt;/span&gt;&#x27;</span>);
    }
  }
</code></pre>
<h2 id="id-faq">FAQ</h2>
<h3 id="id-how-can-i-control-click-on-results-and-have-them-open-in-a-new-tab">How can I <code>Control</code>-click on results and have them open in a new tab?</h3>
<p>You&#39;ll need to update your suggestion templates to make them as <code>&lt;a href&gt;</code> links
and not simple divs. <code>Control</code>-clicking on them will trigger the default browser
behavior and open suggestions in a new tab.</p>
<p>To also support keyboard navigation, you&#39;ll need to listen to the
<code>autocomplete:selected</code> event and change <code>window.location</code> to the destination
URL.</p>
<p>Note that you might need to check the value of <code>context.selectionMethod</code> in
<code>autocomplete:selected</code> first. If it&#39;s equal to <code>click</code>, you should <code>return</code>
early, otherwise your main window will <strong>also</strong> follow the link.</p>
<p>Here is an example of how it would look like:</p>
<pre><code class="hljs language-javascript"><span class="hljs-title function_">autocomplete</span>(…).<span class="hljs-title function_">on</span>(<span class="hljs-string">&#x27;autocomplete:selected&#x27;</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params">event, suggestion, dataset, context</span>) {
  <span class="hljs-comment">// Do nothing on click, as the browser will already do it</span>
  <span class="hljs-keyword">if</span> (context.<span class="hljs-property">selectionMethod</span> === <span class="hljs-string">&#x27;click&#x27;</span>) {
    <span class="hljs-keyword">return</span>;
  }
  <span class="hljs-comment">// Change the page, for example, on other events</span>
  <span class="hljs-variable language_">window</span>.<span class="hljs-property">location</span>.<span class="hljs-title function_">assign</span>(suggestion.<span class="hljs-property">url</span>);
});
</code></pre>
<h2 id="id-events">Events</h2>
<p>The autocomplete component triggers the following custom events.</p>
<ul>
<li><p><code>autocomplete:opened</code> – Triggered when the dropdown menu of the autocomplete is
opened.</p>
</li>
<li><p><code>autocomplete:shown</code> – Triggered when the dropdown menu of the autocomplete is
shown (opened and non-empty).</p>
</li>
<li><p><code>autocomplete:empty</code> – Triggered when all datasets are empty.</p>
</li>
<li><p><code>autocomplete:closed</code> – Triggered when the dropdown menu of the autocomplete is
closed.</p>
</li>
<li><p><code>autocomplete:updated</code> – Triggered when a dataset is rendered.</p>
</li>
<li><p><code>autocomplete:cursorchanged</code> – Triggered when the dropdown menu cursor is moved
to a different suggestion. The event handler will be invoked with 3
arguments: the jQuery event object, the suggestion object, and the name of
the dataset the suggestion belongs to.</p>
</li>
<li><p><code>autocomplete:selected</code> – Triggered when a suggestion from the dropdown menu is
selected. The event handler will be invoked with the following arguments: the jQuery
event object, the suggestion object, the name of the dataset the
suggestion belongs to and a <code>context</code> object. The <code>context</code> contains
a <code>.selectionMethod</code> key that can be either <code>click</code>, <code>enterKey</code>, <code>tabKey</code> or
<code>blur</code>, depending how the suggestion was selected.</p>
</li>
<li><p><code>autocomplete:cursorremoved</code> – Triggered when the cursor leaves the selections
or its current index is lower than 0</p>
</li>
<li><p><code>autocomplete:autocompleted</code> – Triggered when the query is autocompleted.
Autocompleted means the query was changed to the hint. The event handler will
be invoked with 3 arguments: the jQuery event object, the suggestion object,
and the name of the dataset the suggestion belongs to.</p>
</li>
<li><p><code>autocomplete:redrawn</code> – Triggered when <code>appendTo</code> is used and the wrapper is resized/repositionned.</p>
</li>
</ul>
<p>All custom events are triggered on the element initialized as the autocomplete.</p>
<h2 id="id-api">API</h2>
<h3 id="id-jquery-1">jQuery</h3>
<p>Turns any <code>input[type=&quot;text&quot;]</code> element into an auto-completion menu. <code>globalOptions</code> is an
options hash that&#39;s used to configure the autocomplete to your liking. Refer to
<a href="#global-options">Global Options</a> for more info regarding the available configs. Subsequent
arguments (<code>*datasets</code>), are individual option hashes for datasets. For more
details regarding datasets, refer to <a href="#datasets">Datasets</a>.</p>
<pre><code>$(selector).autocomplete(globalOptions, datasets)
</code></pre>
<p>Example:</p>
<pre><code class="hljs language-js">$(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>({
  <span class="hljs-attr">minLength</span>: <span class="hljs-number">3</span>
},
{
  <span class="hljs-attr">name</span>: <span class="hljs-string">&#x27;my-dataset&#x27;</span>,
  <span class="hljs-attr">source</span>: mySource
});
</code></pre>
<h4 id="id-jqueryautocompletedestroy">jQuery#autocomplete(&#39;destroy&#39;)</h4>
<p>Removes the autocomplete functionality and reverts the <code>input</code> element back to its
original state.</p>
<pre><code class="hljs language-js">$(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;destroy&#x27;</span>);
</code></pre>
<h4 id="id-jqueryautocompleteopen">jQuery#autocomplete(&#39;open&#39;)</h4>
<p>Opens the dropdown menu of the autocomplete. Note that being open does not mean that
the menu is visible. The menu is only visible when it is open and has content.</p>
<pre><code class="hljs language-js">$(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;open&#x27;</span>);
</code></pre>
<h4 id="id-jqueryautocompleteclose">jQuery#autocomplete(&#39;close&#39;)</h4>
<p>Closes the dropdown menu of the autocomplete.</p>
<pre><code class="hljs language-js">$(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;close&#x27;</span>);
</code></pre>
<h4 id="id-jqueryautocompleteval">jQuery#autocomplete(&#39;val&#39;)</h4>
<p>Returns the current value of the autocomplete. The value is the text the user has
entered into the <code>input</code> element.</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> myVal = $(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;val&#x27;</span>);
</code></pre>
<h4 id="id-jqueryautocompleteval-val">jQuery#autocomplete(&#39;val&#39;, val)</h4>
<p>Sets the value of the autocomplete. This should be used in place of <code>jQuery#val</code>.</p>
<pre><code class="hljs language-js">$(<span class="hljs-string">&#x27;.search-input&#x27;</span>).<span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;val&#x27;</span>, myVal);
</code></pre>
<h4 id="id-jqueryfnautocompletenoconflict">jQuery.fn.autocomplete.noConflict()</h4>
<p>Returns a reference to the autocomplete plugin and reverts <code>jQuery.fn.autocomplete</code>
to its previous value. Can be used to avoid naming collisions.</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> autocomplete = jQuery.<span class="hljs-property">fn</span>.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">noConflict</span>();
jQuery.<span class="hljs-property">fn</span>.<span class="hljs-property">_autocomplete</span> = autocomplete;
</code></pre>
<h3 id="id-standalone-1">Standalone</h3>
<p>The standalone version API is similiar to jQuery&#39;s:</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> search = <span class="hljs-title function_">autocomplete</span>(containerSelector, globalOptions, datasets);
</code></pre>
<p>Example:</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> search = <span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;#search&#x27;</span>, { <span class="hljs-attr">hint</span>: <span class="hljs-literal">false</span> }, [{
  <span class="hljs-attr">source</span>: autocomplete.<span class="hljs-property">sources</span>.<span class="hljs-title function_">hits</span>(index, { <span class="hljs-attr">hitsPerPage</span>: <span class="hljs-number">5</span> })
}]);

search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">open</span>();
search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">close</span>();
search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">getVal</span>();
search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">setVal</span>(<span class="hljs-string">&#x27;Hey Jude&#x27;</span>);
search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">destroy</span>();
search.<span class="hljs-property">autocomplete</span>.<span class="hljs-title function_">getWrapper</span>(); <span class="hljs-comment">// since autocomplete.js wraps your input into another div, you can access that div</span>
</code></pre>
<p>You can also pass a custom Typeahead instance in Autocomplete.js constructor:</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> search = <span class="hljs-title function_">autocomplete</span>(<span class="hljs-string">&#x27;#search&#x27;</span>, { <span class="hljs-attr">hint</span>: <span class="hljs-literal">false</span> }, [{ ... }], <span class="hljs-keyword">new</span> <span class="hljs-title class_">Typeahead</span>({ ... }));
</code></pre>
<h4 id="id-autocompletenoconflict">autocomplete.noConflict()</h4>
<p>Returns a reference to the autocomplete plugin and reverts <code>window.autocomplete</code>
to its previous value. Can be used to avoid naming collisions.</p>
<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> algoliaAutocomplete = autocomplete.<span class="hljs-title function_">noConflict</span>();
</code></pre>
<h2 id="id-contributing--releasing">Contributing &amp; releasing</h2>
<p>see <a href="./CONTRIBUTING.md">CONTRIBUTING.md</a></p>
<h2 id="id-credits">Credits</h2>
<p>This library has originally been forked from <a href="https://github.com/twitter/typeahead.js">Twitter&#39;s typeahead.js</a> library.</p>