Basic configuration options

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.

Yet, 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).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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;
          },
        },
      },
    ];
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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 options 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.

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

This is all you need to build a fully functional, accessible, keyboard-navigable autocomplete.

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 the user types 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 execute 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, check out the API reference.