Skip to main content
Autocomplete v1 offers many new features that are explained in Core concepts. Please read this documentation to understand the new capabilities.

​
Import

JavaScript
// v0
import autocomplete from "autocomplete.js"; 

// v1
import { autocomplete } from "@algolia/autocomplete-js";

​
Container

Autocomplete now takes a container (for example, a <div>), not an <input>. Autocomplete generates a fully accessible search box for you.
HTML
<!-- v0 -->
<input id="autocomplete" />

<!-- v1 -->
<div id="autocomplete"></div>
Read more about installation options in the Getting Started guide.

​
Parameters

These parameters and how you use them have changed from Autocomplete v0:
v0v1
autocomplete('#autocomplete', ...)autocomplete({ container: '#autocomplete', ...})
autoselect: truedefaultActiveItemId: 0
autoselectOnBlur: trueNo longer needed. This is the default behavior
tabAutocomplete: trueNo longer supported. v1 implements the ARIA 1.1 form of the combobox design pattern
hintNo longer supported
clearOnSelectedThis is now local to the source: getItemInputValue: () => ''
dropdownMenuContainerpanelContainer
templates (top-level)templates (see also render and renderNoResults)
cssClassesclassNames where properties have changed
keyboardShortcutsNo longer supported as an option. Check out the keyboard navigation docs
minLength: 0openOnFocus: true

​
Datasets

Datasets are replaced by the getSources function. Learn more about Sources concept.

​
Sources

Sources are replaced by getItems.

​
Templates

Autocomplete v1 renamed some templates, and uses an agnostic virtual DOM implementation to render them.

​
Return HTML

Unlike in v0, you can no longer return plain HTML strings to inject into the DOM. Yet, you can still return HTML strings using the provided html tagged function.
The html function is available in Autocomplete v1.6.0 and later.
autocomplete(
  // ...
  [
    {
      // ...
      templates: {
        header: '<div class="header">Products</div>',
        suggestion: function (item) {
          const name = item._highlightResult.name.value;

          return `<div>
            <img class="thumbnail" src="${item.image}" />
            <a href="${item.url}">${autocomplete.escapeHighlightedString(
              name,
              '<em>',
              '</em>'
            )}</a>
          </div>`;
        },
      },
    },
  ]
);
Please refer to the Returning HTML section of the Templates guide for a full overview and to learn how to support Internet Explorer 11.
If you’re already using a virtual DOM in your app, you can provide it to Autocomplete and directly return JSX from templates.

​
Renamed templates

Some templates from v0 were renamed in v1.
  • The suggestion template is now item.
  • The empty template is now noResults.
For more information, see Templates.

​
New renderer.render option

Starting from v1.6.0, Autocomplete introduces a new render property in the renderer option to pass a custom render function when using Autocomplete with a custom virtual DOM implementation (React, Vue). If you were using the render option to specify a custom render function, you can now remove it and pass the function to renderer instead.
JSX
import { createElement, Fragment } from "react";
import { render } from "react-dom";

autocomplete({
  // ...
  renderer: { createElement, Fragment }, 
  renderer: { createElement, Fragment, render }, 
  render({ children }, root) {
    render(children, root);
  },
});
If you were using the render option to customize the layout, you can also use the new renderer.render option and access your custom render function in the provided render parameters.
JSX
import { createElement, Fragment } from "react";
import { render } from "react-dom"; 
import { render as reactRender } from "react-dom"; 

autocomplete({
  // ...
  renderer: { createElement, Fragment }, 
  renderer: { createElement, Fragment, render: reactRender }, 
  render({ children }, root) { 
  render({ children, render }, root) { 
    render(`<div>${children}</div>`, root);
  },
});

​
Top-level API

JavaScript
const search = autocomplete(/* ... */);

search.autocomplete.open(); 
search.autocomplete.close();
search.autocomplete.getVal();
search.autocomplete.setVal("Query");
search.autocomplete.destroy();

search.setIsOpen(true); 
search.setIsOpen(false);
search.setQuery("Query");
search.destroy();

​
Full example

import autocomplete from "autocomplete.js";

autocomplete(
  "#autocomplete",
  {
    cssClasses: {
      dropdownMenu: "search-suggestion-wrapper",
    },
  },
  [
    {
      source: autocomplete.sources.hits(searchClient.initIndex("products"), {
        hitsPerPage: 3,
        distinct: true,
      }),
      templates: {
        header: '<div class="header">Products</div>',
        suggestion: function (item) {
          const name = item._highlightResult.name.value;

          return `<div>
            <img class="thumbnail" src="${item.image}" />
            <a href="${item.url}">${autocomplete.escapeHighlightedString(
              name,
              "<em>",
              "</em>",
            )}</a>
          </div>`;
        },
      },
    },
  ],
);

​
Upgrade the Algolia JavaScript API client from v4 to v5

Upgrading from algoliasearch v4 to v5 doesn’t introduce any breaking changes. However, when you use the query in the search parameters, you need to use the query parameter instead of the query property.
JavaScript
 getAlgoliaResults({
   searchClient,
   queries: [
     {
       indexName: "YOUR_INDEX_NAME",
       query, 
       params: {
         query,
       },
     },
   ],
 });
⌘I