Populating autocomplete with sources

Sources define where to retrieve items from and their behavior.

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.

The most important aspect of an autocomplete experience is the items you display. They’re usually search results for a but there are other ways to use them.

Static sources

The most straightforward way to provide items is to return static sources. Each source returns a collection of items.

JavaScript

autocomplete({
  // ...
  getSources() {
    return [
      {
        sourceId: "links",
        getItems() {
          return [
            { label: "Twitter", url: "https://twitter.com" },
            { label: "GitHub", url: "https://github.com" },
          ];
        },
        getItemUrl({ item }) {
          return item.url;
        },
        // ...
      },
    ];
  },
});

Whatever the autocomplete state, it always returns these two items.

Search in static sources

Access the autocomplete state in your sources to search within static sources and update them as users type.

JavaScript

autocomplete({
  // ...
  getSources() {
    return [
      {
        sourceId: "links",
        getItems({ query }) {
          return [
            { label: "Twitter", url: "https://twitter.com" },
            { label: "GitHub", url: "https://github.com" },
          ].filter(({ label }) =>
            label.toLowerCase().includes(query.toLowerCase()),
          );
        },
        getItemUrl({ item }) {
          return item.url;
        },
        // ...
      },
    ];
  },
});

Before moving on to more complex sources, here’s a closer look at the code.

The getSources function returns an array of sources. Each source implements a getItems function to return the items to display. These items can be a simple static array, but you can also use a function to refine items based on the query. The getItems function is called whenever the input changes.

By default, autocomplete items are meant to be hyperlinks. To decide which page to visit, create a getItemURL function. It enables the keyboard accessibility feature, allowing users to open items in the current tab, a new tab, or a new window from their keyboard.

Customize items with templates

In addition to defining data sources for items, a source lets you customize how to display items with templates.

JavaScript

autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        // ...
        templates: {
          item({ item }) {
            return `Result: ${item.name}`;
          },
        },
      },
    ];
  },
});

Display header and footer elements around the list of items:

JavaScript

autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        // ...
        templates: {
          header() {
            return "Suggestions";
          },
          item({ item }) {
            return `Result: ${item.name}`;
          },
          footer() {
            return "Footer";
          },
        },
      },
    ];
  },
});

Templates aren’t limited to strings. You can provide any valid virtual DOM element.

Dynamic sources

Static sources can be useful, especially when users haven’t typed anything. However, you might want more robust search capabilities beyond exact matches in strings.

In this case, you could search into one or more Algolia indices using the built-in getAlgoliaResults function.

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

autocomplete({
  // ...
  getSources() {
    return [
      {
        sourceId: "products",
        getItems({ query }) {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search",
                query,
              },
            ],
          });
        },
        getItemUrl({ item }) {
          return item.url;
        },
        // ...
      },
    ];
  },
});

Asynchronous sources

The getSources function supports promises to fetch sources from any asynchronous API, such as Algolia or any third-party API you can query with an HTTP request.

For example, you could use Google Places Query Autocomplete to search for locations and retrieve popular queries that match points of interest.

JavaScript

autocomplete({
  // ...
  getSources({ query }) {
    return fetch(
      `https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=${query}&key=YOUR_GOOGLE_PLACES_API_KEY`,
    )
      .then((response) => response.json())
      .then(({ predictions }) => {
        return [
          {
            sourceId: "predictions",
            getItems() {
              return predictions;
            },
            getItemInputValue({ item }) {
              return item.description;
            },
            // ...
          },
        ];
      });
  },
});

The getItemInputValue function returns the value of the item. It lets you fill the search box with a new value whenever users select an item, allowing them to refine their query and retrieve more relevant results.

Multiple sources

You don’t have to return just one set of results. Autocomplete lets you fetch data from several sources and show different kinds of results that are used for different things.

For example, you may want to display Algolia search results and Query Suggestions.

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        sourceId: "querySuggestions",
        getItems() {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search_demo_query_suggestions",
                query,
              },
            ],
          });
        },
        getItemInputValue() {
          return item.query;
        },
        // ...
      },
      {
        sourceId: "products",
        getItems() {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search",
                query,
              },
            ],
          });
        },
        getItemUrl({ item }) {
          return item.url;
        },
        // ...
      },
    ];
  },
});

Use the autocomplete-plugin-query-suggestions plugin to retrieve Query Suggestions.

For more information, see Including multiple result types.

Reference

getSources · function

Type definition

(params: {
  query: string,
  state: AutocompleteState,
  ...setters: Autocomplete Setters
}) => Array<AutocompleteSource> | Promise<Array<AutocompleteSource>>

The function to fetch sources and their behaviors. Returns a list of AutocompleteSource objects.

See also: setter

AutocompleteSource

sourceId · string

Unique identifier for the source. It’s used as value for the data-autocomplete-source-id attribute of the source section container.

getItems · function · required

Type definition

(params: { query: string, state: AutocompleteState, ...setters }) => Item[] | Promise<Item[]>

The function called when the input changes. You can use this function to filter the items based on the query.

Example

const items = [{ value: "Apple" }, { value: "Banana" }];

const source = {
  getItems({ query }) {
    return items.filter((item) => item.value.includes(query));
  },
  // ...
};

getItemInputValue · function · default: ({ state }) => state.query

Type definition

(params: { item: Item; state: AutocompleteState }) => string;

The function called to get the value of an item. The value is used to fill the search box.

Example

const items = [{ value: "Apple" }, { value: "Banana" }];

const source = {
  getItemInputValue({ item }) {
    return item.value;
  },
  // ...
};

getItemUrl · function

Type definition

(params: { item: Item; state: AutocompleteState }) => string | undefined;

The function called to get the URL of the item. The value is used to add keyboard accessibility features to let users open items in the current tab, a new tab, or a new window.

Example

const items = [
  { value: "Google", url: "https://google.com" },
  { value: "Amazon", url: "https://amazon.com" },
];

const source = {
  getItemUrl({ item }) {
    return item.url;
  },
  // ...
};

onSelect · function · default: ({ setIsOpen }) => setIsOpen(false)

Type definition

(params: {
  state: AutocompleteState,
  ...setters,
  event: Event,
  item: TItem,
  itemInputValue: string,
  itemUrl: string,
  source: AutocompleteSource 
}) => void

The function called whenever an item is selected.

Example

const items = [{ value: "Apple" }, { value: "Banana" }];

const source = {
  onSelect({ item, setQuery }) {
    setQuery(item.value);
  },
  // ...
};

onActive · function

Type definition

(params: {
  state: AutocompleteState,
  ...setters,
  event: Event,
  item: TItem,
  itemInputValue: string,
  itemUrl: string,
  source: AutocompleteSource
}) => void

The function called whenever an item is active.

You can trigger different behaviors if the item is active depending on the triggering event using the event parameter.

templates · AutocompleteTemplates

A set of templates to customize how sections and their items are displayed.

For more information, see Displaying items with Templates.