> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Autocomplete to v1

> Learn how to upgrade from Autocomplete v0 to Autocomplete v1.

<Tip>
  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](/doc/api-reference/widgets/autocomplete/js) or
  [React InstantSearch](/doc/api-reference/widgets/autocomplete/react).
</Tip>

Autocomplete v1 offers many new features that are explained in [Core concepts](/doc/ui-libraries/autocomplete/core-concepts/basic-configuration-options).
Read this documentation to understand the new capabilities.

## Import

```js JavaScript icon=code theme={"system"}
// v0
import autocomplete from "autocomplete.js"; // [!code --]

// v1
import { autocomplete } from "@algolia/autocomplete-js"; // [!code ++]
```

## Container

Autocomplete now takes a container (for example, a `<div>`), not an `<input>`.
Autocomplete generates a fully accessible search box for you.

```html HTML icon=code-xml theme={"system"}
<!-- v0 -->
<input id="autocomplete" /> <!-- [!code --] -->

<!-- v1 -->
<div id="autocomplete"></div> <!-- [!code ++] -->
```

Read more about [installation options](/doc/ui-libraries/autocomplete/introduction/getting-started#installation)
in the [Getting Started](/doc/ui-libraries/autocomplete/introduction/getting-started) guide.

## Parameters

These parameters and how you use them have changed from [Autocomplete v0](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options):

| v0                                                                                                                                                     | v1                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`autocomplete('#autocomplete', ...)`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options) | [`autocomplete({ container: '#autocomplete', ...})`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-container)                                                                                                                                                                |
| [`autoselect: true`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                   | `defaultActiveItemId: 0`                                                                                                                                                                                                                                                                                       |
| [`autoselectOnBlur: true`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)             | No longer needed. This is the default behavior                                                                                                                                                                                                                                                                 |
| [`tabAutocomplete: true`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)              | No longer supported. v1 implements the ARIA 1.1 form of the [combobox design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)                                                                                                                                                                      |
| [`hint`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                               | No longer supported                                                                                                                                                                                                                                                                                            |
| [`clearOnSelected`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                    | This is now local to the [source](/doc/ui-libraries/autocomplete/core-concepts/sources): [`getItemInputValue: () => ''`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-item-input-value)                                                                                                      |
| [`dropdownMenuContainer`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)              | [`panelContainer`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-panel-container)                                                                                                                                                                                            |
| [`templates`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options) (top-level)              | [`templates`](/doc/ui-libraries/autocomplete/core-concepts/templates) (see also [`render`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-render) and [`renderNoResults`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-render-no-results)) |
| [`cssClasses`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                         | [`classNames`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-class-names) where properties have changed                                                                                                                                                                      |
| [`keyboardShortcuts`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                  | No longer supported as an option. Check out the [keyboard navigation docs](/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation)                                                                                                                                                                   |
| [`minLength: 0`](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#global-options)                       | [`openOnFocus: true`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-open-on-focus)                                                                                                                                                                                           |

## Datasets

[Datasets](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#datasets) are replaced by the [`getSources`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-get-sources) function. Learn more about [Sources concept](/doc/ui-libraries/autocomplete/core-concepts/sources).

## Sources

[Sources](https://github.com/algolia/autocomplete/blob/45fa32d008620cf52bf4a90530be338543dfba7f/README.md#sources) are replaced by [`getItems`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-items).

## 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.

<Note>
  The `html` function is available in Autocomplete v1.6.0 and later.
</Note>

<CodeGroup>
  ```tsx v0 theme={"system"}
  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>`;
          },
        },
      },
    ]
  );

  ```

  ```tsx v1 theme={"system"}
  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>`;
            },
          },
        },
      ];
    },
  });
  ```
</CodeGroup>

See the [Returning HTML](/doc/ui-libraries/autocomplete/core-concepts/templates#return-html) section of the [Templates](/doc/ui-libraries/autocomplete/core-concepts/templates) guide for a full overview and to learn how to support Internet Explorer 11.

<Note>
  If you're already using a virtual DOM in your app,
  you can [provide it to Autocomplete](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-renderer) and [directly return JSX from templates](/doc/ui-libraries/autocomplete/core-concepts/templates#return-virtual-nodes-directly).
</Note>

### Renamed templates

Some templates from v0 were renamed in v1.

* The `suggestion` template is now [`item`](/doc/ui-libraries/autocomplete/core-concepts/templates#param-templates-item).
* The `empty` template is now [`noResults`](/doc/ui-libraries/autocomplete/core-concepts/templates#param-templates-no-results).

For more information, see [Templates](/doc/ui-libraries/autocomplete/core-concepts/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 JSX icon=code theme={"system"}
import { createElement, Fragment } from "react";
import { render } from "react-dom";

autocomplete({
  // ...
  renderer: { createElement, Fragment }, // [!code --]
  renderer: { createElement, Fragment, render }, // [!code ++]
  render({ children }, root) {
    // [!code --:2]
    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 JSX icon=code theme={"system"}
import { createElement, Fragment } from "react";
import { render } from "react-dom"; // [!code --]
import { render as reactRender } from "react-dom"; // [!code ++]

autocomplete({
  // ...
  renderer: { createElement, Fragment }, // [!code --]
  renderer: { createElement, Fragment, render: reactRender }, // [!code ++]
  render({ children }, root) { // [!code --]
  render({ children, render }, root) { // [!code ++]
    render(`<div>${children}</div>`, root);
  },
});
```

## Top-level API

```js JavaScript icon=code theme={"system"}
const search = autocomplete(/* ... */);

search.autocomplete.open(); // [!code --:5]
search.autocomplete.close();
search.autocomplete.getVal();
search.autocomplete.setVal("Query");
search.autocomplete.destroy();

search.setIsOpen(true); // [!code ++:4]
search.setIsOpen(false);
search.setQuery("Query");
search.destroy();
```

## Full example

<CodeGroup>
  ```jsx v0 theme={"system"}
  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>`;
          },
        },
      },
    ],
  );
  ```

  ```jsx v1 theme={"system"}
  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",
                    }),
                  ),
                ),
              );
            },
          },
        },
      ];
    },
  });
  ```
</CodeGroup>

## 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.

```js JavaScript icon=code theme={"system"}
 getAlgoliaResults({
   searchClient,
   queries: [
     {
       indexName: "YOUR_INDEX_NAME",
       query, // [!code --]
       params: {
         // [!code ++:3]
         query,
       },
     },
   ],
 });
```