Basic configuration options

Prefer using the Autocomplete widget from InstantSearch instead of the standalone Autocomplete library. It integrates more closely with your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

Autocomplete gives you unlimited flexibility while freeing you from having to think about things like keyboard navigation, accessibility, or UI state. The library offers a wide variety of APIs to let you fully customize the behavior and rendering of your autocomplete.

Open CodeSandbox

Run and edit the Basic configuration options example in CodeSandbox.

Only two parameters are required to create an autocomplete:

The container you want your autocomplete to go in.
The sources from which to get the items to display (see more in Sources).

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

autocomplete({
  container: "#autocomplete",
  getSources() {
    return [
      {
        sourceId: "links",
        getItems({ query }) {
          const items = [
            { label: "Twitter", url: "https://twitter.com" },
            { label: "GitHub", url: "https://github.com" },
          ];

          return items.filter(({ label }) =>
            label.toLowerCase().includes(query.toLowerCase()),
          );
        },
        getItemUrl({ item }) {
          return item.url;
        },
        templates: {
          item({ item }) {
            return item.label;
          },
        },
      },
    ];
  },
});

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

type AutocompleteItem = {
  label: string;
  url: string;
};

autocomplete<AutocompleteItem>({
  container: "#autocomplete",
  getSources() {
    return [
      {
        sourceId: "links",
        getItems({ query }) {
          const items = [
            { label: "Twitter", url: "https://twitter.com" },
            { label: "GitHub", url: "https://github.com" },
          ];

          return items.filter(({ label }) =>
            label.toLowerCase().includes(query.toLowerCase()),
          );
        },
        getItemUrl({ item }) {
          return item.url;
        },
        templates: {
          item({ item }) {
            return item.label;
          },
        },
      },
    ];
  },
});

The container option refers to where to inject the autocomplete in your HTML. It can be a CSS selector or an Element. Make sure to provide a container (like a div), not an input. Autocomplete generates a fully accessible search box for you.

HTML

<div id="autocomplete"></div>

Now, this is a great start, but you can go much further. Here are some options you’ll probably want to use next:

Use placeholder to define the text that appears in the input before users type anything.
Use autoFocus to focus on the search box on page load, and openOnFocus to display items as soon as a user selects the autocomplete, even without typing.
Use the onStateChange lifecycle hook to run code whenever the state changes.
Use debug: true to keep the autocomplete panel open even when the blur event occurs (see Debugging).

For a full list of all available parameters, see the API reference.