autocomplete.js
Advanced tools
This JavaScript library adds a fast and fully-featured auto-completion menu to your search box displaying results "as you type". It can easily be combined with Algolia's realtime search engine. The library is available as a jQuery plugin or an Angular.js directive.
The autocomplete.js library must be included after jQuery and/or Angular.js.
We recommend including it from a CDN:
<script src="//cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js"></script>
<!-- OR -->
<script src="//cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/autocomplete.js/<VERSION>/autocomplete.jquery.min.js"></script>
<!-- OR -->
<script src="//cdnjs.cloudflare.com/ajax/libs/autocomplete.js/<VERSION>/autocomplete.angular.min.js"></script>
Or you can fetch the sources:
You can find the builded version in dist/.
You can require it and use Browserify:
var autocomplete = require('autocomplete.js');
To turn any HTML <input /> into a simple and fast as-you-type auto-completion menu following one of the 2 next sections:
autocomplete.jquery.min.js after including jQueryautocomplete jQuery plugin<input type="text" id="search-input" />
<!-- [ ... ] -->
<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js"></script>
<script>
var client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey')
var index = client.initIndex('YourIndex');
$('#search-input').autocomplete({ hint: false }, [
{
source: index.ttAdapter({ hitsPerPage: 5 }),
displayKey: 'my_attribute',
templates: {
suggestion: function(suggestion) {
return suggestion._highlightResult.my_attribute.value;
}
}
}
]).on('autocomplete:selected', function(even, suggestion, dataset) {
console.log(suggestion, dataset);
});
</script>
autocomplete.angular.min.js after including jQuery & Angular.jsalgolia.autocomplete moduleautocomplete, aa-datasets and the optional aa-options attribute to your search bar<div ng-controller="yourController">
<input type="text" id="search-input" autocomplete aa-datasets="getDatasets()" />
</div>
<!-- [ ... ] -->
<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.min.js"></script>
<script src="//cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js"></script>
<script>
angular.module('myApp', ['algoliasearch', 'algolia.autocomplete'])
.controller('yourController', ['$scope', 'algolia', function($scope, algolia) {
var client = algolia.Client('YourApplicationID', 'YourSearchOnlyAPIKey');
var index = client.initIndex('YourIndex');
$scope.getDatasets = function() {
return {
source: index.ttAdapter({ hitsPerPage: 5 }),
displayKey: 'my_attribute',
templates: {
suggestion: function(suggestion) {
return suggestion._highlightResult.my_attribute.value;
}
}
};
};
$scope.$on('autocomplete:selected', function(event, suggestion, dataset) {
console.log(suggestion, dataset);
});
}]);
</script>
Below is a faux mustache template describing the DOM structure of an autocomplete
dropdown menu. Keep in mind that header, footer, suggestion, and empty
come from the provided templates detailed here.
<span class="aa-dropdown-menu{{#datasets}} aa-{{'with' or 'without'}}-{{name}}{{/datasets}}">
{{#datasets}}
<div class="aa-dataset-{{name}}">
{{{header}}}
<span class="aa-suggestions">
{{#suggestions}}
<div class="aa-suggestion">{{{suggestion}}}</div>
{{/suggestions}}
{{^suggestions}}
{{{empty}}}
{{/suggestions}}
</span>
{{{footer}}}
</div>
{{/datasets}}
</span>
When an end-user mouses or keys over a .aa-suggestion, the class aa-cursor will be added to it. You can use this class as a hook for styling the "under cursor" state of suggestions.
Add the following CSS rules to add a default style:
.algolia-autocomplete {
width: 100%;
}
.algolia-autocomplete .aa-input, .algolia-autocomplete .aa-hint {
width: 100%;
}
.algolia-autocomplete .aa-hint {
color: #999;
}
.algolia-autocomplete .aa-dropdown-menu {
width: 100%;
background-color: #fff;
border: 1px solid #999;
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: #B2D7FF;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion em {
font-weight: bold;
font-style: normal;
}
Here is what the basic example looks like:
When initializing an autocomplete, there are a number of options you can configure.
hint – If false, the autocomplete will not show a hint. Defaults to true.
debug – If true, the autocomplete will not close on blur. Defaults to false.
openOnFocus – If true, the dropdown menu will open when the input is focused. Defaults to false.
templates – An optional hash overriding the default templates.
dropdownMenu – the dropdown menu template. The template should include all dataset placeholders.header – the header to prepend to the dropdown menufooter – the footer to append to the dropdown menu<script type="text/template" id="my-custom-menu-template">
<div class="my-custom-menu">
<div class="row">
<div class="col-sm-6">
<div class="aa-dataset-contacts1"></div>
</div>
<div class="col-sm-6">
<div class="aa-dataset-contacts2"></div>
<div class="aa-dataset-contacts3"></div>
</div>
</div>
</div>
</script>
<script>
$('#search-input').autocomplete(
{
templates: {
dropdownMenu: '#my-custom-menu-template',
footer: '<div class="branding">Powered by <img src="https://www.algolia.com/assets/algolia128x40.png" /></div>'
}
},
[
{
source: index.ttAdapter({ hitsPerPage: 5 }),
name: 'contacts1',
templates: {
header: '<h4>List 1</h4>',
suggestion: function(suggestion) {
// FIXME
}
}
},
{
source: index.ttAdapter({ hitsPerPage: 2 }),
name: 'contacts2',
templates: {
header: '<h4>List 2</h4>',
suggestion: function(suggestion) {
// FIXME
}
}
},
{
source: index.ttAdapter({ hitsPerPage: 2 }),
name: 'contacts3',
templates: {
header: '<h4>List 3</h4>',
suggestion: function(suggestion, answer) {
// FIXME
}
}
}
]
);
</script>
minLength – The minimum character length needed before suggestions start
getting rendered. Defaults to 1.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.
Datasets can be configured using the following options.
source – The backing data source for suggestions. Expected to be a function
with the signature (query, cb). It is expected that the function will
compute the suggestion set (i.e. an array of JavaScript objects) for query
and then invoke cb with said set. cb can be invoked synchronously or
asynchronously.
name – The name of the dataset. This will be appended to tt-dataset- to
form the class name of the containing DOM element. Must only consist of
underscores, dashes, letters (a-z), and numbers. Defaults to a random
number.
displayKey – 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
value.
templates – 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.
empty – Rendered when 0 suggestions are available for the given query.
Can be either a HTML string or a precompiled template. If it's a precompiled
template, the passed in context will contain query.
footer– Rendered at the bottom of the dataset. Can be either a HTML
string or a precompiled template. If it's a precompiled template, the passed
in context will contain query and isEmpty.
header – Rendered at the top of the dataset. Can be either a HTML string
or a precompiled template. If it's a precompiled template, the passed in
context will contain query and isEmpty.
suggestion – Used to render a single suggestion. If set, this has to be a
precompiled template. The associated suggestion object will serve as the
context. Defaults to the value of displayKey wrapped in a p tag i.e.
<p>{{value}}</p>.
The autocomplete component triggers the following custom events.
autocomplete:opened – Triggered when the dropdown menu of the autocomplete is
opened.
autocomplete:closed – Triggered when the dropdown menu of the autocomplete is
closed.
autocomplete:cursorchanged – 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.
autocomplete:selected – Triggered when a suggestion from the dropdown menu is
selected. 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.
autocomplete:autocompleted – 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.
All custom events are triggered on the element initialized as the autocomplete.
Turns any input[type="text"] element into an auto-completion menu. options is an
options hash that's used to configure the autocomplete to your liking. Refer to
Options for more info regarding the available configs. Subsequent
arguments (*datasets), are individual option hashes for datasets. For more
details regarding datasets, refer to Datasets.
$('.search-input').autocomplete({
minLength: 3
},
{
name: 'my-dataset',
source: mySource
});
Removes the autocomplete functionality and reverts the input element back to its
original state.
$('.search-input').autocomplete('destroy');
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.
$('.search-input').autocomplete('open');
Closes the dropdown menu of the autocomplete.
$('.search-input').autocomplete('close');
Returns the current value of the autocomplete. The value is the text the user has
entered into the input element.
var myVal = $('.search-input').autocomplete('val');
Sets the value of the autocomplete. This should be used in place of jQuery#val.
$('.search-input').autocomplete('val', myVal);
Returns a reference to the autocomplete plugin and reverts jQuery.fn.autocomplete
to its previous value. Can be used to avoid naming collisions.
var autocomplete = jQuery.fn.autocomplete.noConflict();
jQuery.fn._autocomplete = autocomplete;
To start developing, you can use the following commands:
$ npm install
$ npm run dev
$ open http://localhost:8888/test/playground.html
Linting is done with eslint and Algolia's configuration and can be run with:
$ npm run lint
Unit tests are written using Jasmine and ran with Karma. Integration tests are using Mocha and Saucelabs.
To run the unit tests suite run:
$ npm test
To run the integration tests suite run:
$ npm run build
$ npm run server
$ ngrok 8888
$ TEST_HOST=http://YOUR_NGROK_ID.ngrok.com SAUCE_ACCESS_KEY=YOUR_KEY SAUCE_USERNAME=YOUR_USERNAME./node_modules/mocha/bin/mocha --harmony -R spec ./test/integration/test.js
You can check the code style with:
npm run checkstyle
You can fix style issues automatically with:
npm run jsfmt
This library has originally been forked from Twitter's typeahead.js library.
0.4.0 Aug 12, 2015
openOnFocus option to open the dropdown menu when the input is focusedFAQs
Fast and fully-featured autocomplete library
The npm package autocomplete.js receives a total of 97,731 weekly downloads. As such, autocomplete.js popularity was classified as popular.
We found that autocomplete.js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 75 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
The Socket Research Team investigates a malicious Python package that enables automated credit card fraud on WooCommerce stores by abusing real checkout and payment flows.
Security News
Python has adopted a standardized lock file format to improve reproducibility, security, and tool interoperability across the packaging ecosystem.
Security News
OpenGrep has restored fingerprint and metavariable support in JSON and SARIF outputs, making static analysis more effective for CI/CD security automation.