Upgrade Autocomplete to v1

Learn how to upgrade from Autocomplete v0 to Autocomplete v1.

Autocomplete is also available as an experimental widget in InstantSearch, making it easier to integrate into your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

Autocomplete v1 offers many new features that are explained in Core concepts. 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:

v0	v1
autocomplete('#autocomplete', ...)	autocomplete({ container: '#autocomplete', ...})
autoselect: true	defaultActiveItemId: 0
autoselectOnBlur: true	No longer needed. This is the default behavior
tabAutocomplete: true	No longer supported. v1 implements the ARIA 1.1 form of the combobox design pattern
hint	No longer supported
clearOnSelected	This is now local to the source: getItemInputValue: () => ''
dropdownMenuContainer	panelContainer
templates (top-level)	templates (see also render and renderNoResults)
cssClasses	classNames where properties have changed
keyboardShortcuts	No longer supported as an option. Check out the keyboard navigation docs
minLength: 0	openOnFocus: 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.

v0

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

autocomplete({
  // ...
  getSources() {
    return [
      {
        // ...
        templates: {
          header({ html }) {
            // You can still return the same HTML strings using the provided
            // `html` tagged template.
            return html`<div class="header">Products</div>`;
          },
          item({ item, components, html }) {
            // Highlighting and snippeting now comes as a provided component to
            // which you can pass the full item and the attribute to highlight.
            return html`<div>
              <img class="thumbnail" src="${item.image}" /><a href="${item.url}"
                >${components.Highlight({
                  hit: item,
                  attribute: 'name',
                  tagName: 'em',
                })}</a
              >
            </div>`;
          },
        },
      },
    ];
  },
});

See 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

v0

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

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

autocomplete({
  container: "#autocomplete",
  classNames: {
    panel: "search-suggestion-wrapper",
  },
  getSources({ query }) {
    return [
      {
        sourceId: "products",
        getItems({ query }) {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "products",
                params: {
                  query,
                  hitsPerPage: 3,
                  distinct: true,
                },
              },
            ],
          });
        },
        templates: {
          header({ createElement }) {
            return createElement("div", { class: "header" }, "Products");
          },
          item({ item, createElement, components }) {
            return createElement(
              "div",
              null,
              createElement(
                "img",
                { class: "thumbnail", src: item.image },
                createElement(
                  "a",
                  { href: item.url },
                  components.Highlight({
                    hit: item,
                    attribute: "name",
                    tagName: "em",
                  }),
                ),
              ),
            );
          },
        },
      },
    ];
  },
});

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