autocomplete

Shows search results as users type their query in a search box.

This widget is and is subject to change in minor versions.

You are viewing the documentation for InstantSearch.js v4. To upgrade from v3, see the migration guide. Looking for the v3 version of this page? View the v3 docs.

Signature

EXPERIMENTAL_autocomplete({
  container: string | HTMLElement;
  // Optional parameters
  indices?: array,
  showSuggestions?: object,
  showRecent?: boolean | object,
  transformItems?: function,
  onSelect?: function,
  getSearchPageURL?: function,
  searchParameters?: object,
  templates?: object,
  cssClasses?: object,
  placeholder?: string,
  detachedMediaQuery?: string,
})

Import

Package manager

import { EXPERIMENTAL_autocomplete } from "instantsearch.js/es/widgets";

About this widget

The autocomplete widget is one of the most common widgets in a search UI. With this widget, users can get search results as they type their query.

This widget includes a showSuggestions feature that displays query suggestions from a separate index.

Examples

EXPERIMENTAL_autocomplete({
  container: '#autocomplete',
  showSuggestions: {
    indexName: 'query_suggestions',
    getURL: (item) => `/search?q=${item.query}`,
  },
  indices: [
    {
      indexName: 'instant_search',
      getQuery: (item) => item.name,
      getUrl: (item) => `/search?q=${item.name}`,
      templates: {
        header: (_, { html }) => html`<div>Products</div>`,
        item: ({ item, onSelect }, { html }) =>
          html`<div onClick=${onSelect}>${item.name}</div>`,
      },
    },
  ],
})

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

EXPERIMENTAL_autocomplete({
  container: "#autocomplete",
});

indices · array · required

An array of objects that define the indices to query and how to display the results.

• indexName: the name of the index to query
• getQuery: preprocess the query before it is sent for search
• getUrl: update the url to send the search request
• searchParameters: additional search parameters to send with the search request
• templates: the templates to use for the index

JavaScript

EXPERIMENTAL_autocomplete({
  indices: [
    {
      indexName: "instant_search",
      getQuery: (item) => item.name,
      getUrl: (item) => `/search?q=${item.name}`,
      searchParameters: {
        hitsPerPage: 5,
      },
      templates: {
        header: ({ items }, { html }) =>
          html`<div>Products (${items.length} results)</div>`,
        item: ({ item, onSelect }, { html, components }) =>
          html`<div onClick=${onSelect}>
            ${components.ReverseHighlight({ hit: item, attribute: 'name' })}
          </div>`,
      },
    },
  ],
});

showSuggestions · object

Configures the query suggestions feature.

• indexName: the name of the index to query for suggestions
• getURL: update the url to send the search request
• templates: the templates to use for the suggestions

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  showSuggestions: {
    indexName: "query_suggestions",
    getURL: (item) => `/search?q=${item.query}`,
    templates: {
      header: ({ items }, { html }) =>
        html`Suggestions (${items.length} results)`,
      item: ({ item, onSelect }, { html, components }) =>
        html`<div onClick=${onSelect}>
          ${components.ReverseHighlight({ hit: item, attribute: 'query' })}
        </div>`,
    },
  },
});

showRecent · boolean | object

Configures the recent searches feature. Displays previously searched queries stored in local storage.

When set to true, uses default settings. When set to an object, you can configure:

• storageKey: the key to use in local storage (default: ais.recentSearches)
• templates: the templates to use for the recent searches
  • header: template for the header above the recent searches list
  • item: template for each recent search item
• cssClasses: CSS classes to customize the appearance

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  showRecent: true,
});

// With customization
EXPERIMENTAL_autocomplete({
  // ...
  showRecent: {
    storageKey: 'my-app-recent-searches',
    templates: {
      header: ({ items }, { html }) =>
        html`<div>Recent Searches</div>`,
      item: ({ item, onSelect, onRemoveRecentSearch }, { html, components }) =>
        html`<div>
          <button onClick=${onSelect}>
            ${components.ReverseHighlight({ hit: item, attribute: 'query' })}
          </button>
          <button onClick=${onRemoveRecentSearch}>×</button>
        </div>`,
    },
  },
});

transformItems · function

Transforms the items before they are displayed. This function receives an array of index configurations with their hits and should return an array in the same format.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  transformItems(indices) {
    return indices.map((index) => ({
      ...index,
      hits: index.hits.map((hit) => ({
        ...hit,
        _highlightResult: {
          ...hit._highlightResult,
          name: {
            ...hit._highlightResult.name,
            value: hit._highlightResult.name.value.toUpperCase(),
          },
        },
      })),
    }));
  },
});

searchParameters · object

Additional search parameters to send with the search request for every index.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  searchParameters: {
    hitsPerPage: 5,
  },
});

templates · object

The templates to use for the widget.

JavaScript

EXPERMENTAL_autocomplete({
  // ...
  templates: {
    // ...
  },
});

cssClasses · object

The CSS classes you can override:

• root. The widget’s root element.
• list. The list of results.
• item. The list of items.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  cssClasses: {
    root: "MyCustomAutocomplete",
    list: ["MyCustomAutocompleteList", "MyCustomAutocompleteList--subclass"],
    item: "MyCustomAutocompleteItem"
  },
});

templates · object

The templates to use for the widget.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  templates: {
    // ...
  },
});

onSelect · function

A function that is called when the user selects an item. If not provided, the default implementation:

• navigates to the URL of an item if the index configuration defines getURL();
• or navigates to the URL of the search page if autocomplete is not in a search page and getSearchPageURL() is defined;
• or otherwise refines the query

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  onSelect({ query, setQuery, url }) {
    if (inSearchPage && !url) {
      setQuery(query);
      return;
    }
    
    window.location.href = url || `/search?q=${query}`;
  },
});

getSearchPageURL · function

A function that returns the URL of the search page for a given search state.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  getSearchPageURL(nextUiState) {
    return `/search?q=${qs.stringify(nextUiState)}`;
  },
});

placeholder · string

Placeholder text for the search input.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  placeholder: "Search for products...",
});

detachedMediaQuery · string · default: "(max-width: 680px)"

Media query to enable detached (mobile) mode. When the media query matches, the autocomplete switches to a full-screen overlay with a modal interface optimized for mobile devices.

Set to an empty string to disable detached mode. When omitted, it defaults to the CSS variable --ais-autocomplete-detached-media-query, or "(max-width: 680px)" if the variable is not set.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  detachedMediaQuery: "(max-width: 768px)",
});

// Disable detached mode
EXPERIMENTAL_autocomplete({
  // ...
  detachedMediaQuery: "",
});

Templates

You can customize parts of a widget’s UI using the Templates API.

Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

panel · function

Use the template option to customize how the panel is rendered. This is useful when implementing layouts with multiple rows or columns.

The template receives an object containing:

• elements: a key-value dictionary of indices to render. These include regular index names, and special elements like recent and suggestions, if applicable.
• indices: an array containing the data for each index.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  templates: {
    panel: ({ elements, indices }, { html }) => html`
      <div>
        <p>My custom panel</p>
        <div class="left">${elements.suggestions}</div>
        <div class="right">${elements.instant_search}</div>
      </div>
    `,
  },
});

indices[*].templates.header · function

The template to use for the header, before the list of items for that index.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  indices: [
    {
      // ...
      templates: {
        header: ({ items }, { html }) => {
          return html`<div>Products (${items.length} results)</div>`;
        }
      },
    },
  ],
});

indices[*].templates.item · function

The template to use for each item that is returned by the search query on that index.

JavaScript

EXPERIMENTAL_autocomplete({
  // ...
  indices: [
    {
      // ...
      templates: {
        item: ({ item, onSelect }, { html, components }) => {
          return html`<div onClick=${onSelect}>
            ${components.ReverseHighlight({ hit: item, attribute: 'name' })}
          </div>`;
        }
      },
    },
  ],
});