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

# autocomplete

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

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const customLabel_0 = undefined

<Callout icon="flask-conical" color="#14b8a6">
  This widget is **{customLabel_0 || "experimental"}** and is subject to change in minor versions.
</Callout>

<Note>
  You are viewing the documentation for **InstantSearch.js v4**.
  To upgrade from v3, see the [migration guide](/doc/guides/building-search-ui/upgrade-guides/js#upgrade-from-v3-to-v4).
  Looking for the v3 version of this page?
  [View the v3 docs](https://algolia.com/old-docs/deprecated/instantsearch/js/v3/api-reference/autocomplete).
</Note>

```ts Signature theme={"system"}
EXPERIMENTAL_autocomplete({
  container: string | HTMLElement;
  // Optional parameters
  indices?: array,
  feeds?: array,
  showQuerySuggestions?: object,
  showPromptSuggestions?: object,
  showRecent?: boolean | object,
  transformItems?: function,
  onSelect?: function,
  getSearchPageURL?: function,
  searchParameters?: object,
  templates?: object,
  cssClasses?: object,
  escapeHTML?: boolean,
  placeholder?: string,
  autofocus?: boolean,
  detachedMediaQuery?: string,
  translations?: object,
  aiMode?: boolean,
})
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { EXPERIMENTAL_autocomplete } from "instantsearch.js/es/widgets";
  ```

  ```js CDN theme={"system"}
  const { EXPERIMENTAL_autocomplete } = instantsearch.widgets;
  // or directly use instantsearch.widgets.EXPERIMENTAL_autocomplete()
  ```
</CodeGroup>

## 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 `showQuerySuggestions` feature that displays query suggestions from a separate <Index />.

<Note>
  The widget defers registering and querying its indices until the user first focuses the search input.
  This avoids unnecessary network requests on page load.
  When [`autofocus`](#param-autofocus) is enabled, the input is focused on load, so the indices are registered immediately.
</Note>

## Examples

```jsx theme={"system"}
EXPERIMENTAL_autocomplete({
  container: '#autocomplete',
  showQuerySuggestions: {
    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

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    EXPERIMENTAL_autocomplete({
      container: "#autocomplete",
    });
    ```

    ```js HTMLElement theme={"system"}
    EXPERIMENTAL_autocomplete({
      container: document.querySelector("#autocomplete"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="indices" type="array">
  An array of objects that define the indices to query and how to display the results.
  Use either `indices` or [`feeds`](#param-feeds).

  * `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](/doc/api-reference/api-parameters/) to send with the search request
  * `templates`: the [templates](#templates) to use for the index
  * `cssClasses`: CSS classes to customize the appearance.
    * `root`: the index section root element.
    * `list`: the list of results.
    * `header`: the section header.
    * `item`: each result item.
    * `noResults`: the no results element.

  ```js JavaScript icon=code theme={"system"}
  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>`,
        },
      },
    ],
  });
  ```
</ParamField>

<ParamField body="feeds" type="array">
  An array of feed configurations that populate the panel from a single [multifeed composition](/doc/guides/compositions/multifeed-compositions) response instead of querying separate `indices`.
  Use `feeds` to display several result sets that come from one composition.

  The `feeds` and `indices` options are mutually exclusive.
  To use `feeds`, you need a composition-based InstantSearch instance (the `compositionID` option must be set on [`instantsearch`](/doc/api-reference/widgets/instantsearch/js)). See the [`feeds`](/doc/api-reference/widgets/feeds/js) widget for the standalone equivalent.

  Each feed configuration supports these properties:

  * `feedID`: the ID of the feed in the composition response. Each `feedID` must be unique, including feed IDs used in `showQuerySuggestions` and `showPromptSuggestions`.
  * `getQuery`: preprocess the query before it is sent for search.
  * `getURL`: update the URL to send the search request.
  * `templates`: the [templates](#templates) to use for the feed.
  * `cssClasses`: CSS classes to customize the appearance.
    * `root`: the feed section root element.
    * `list`: the list of results.
    * `header`: the section header.
    * `item`: each result item.
    * `noResults`: the no results element.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    feeds: [
      {
        feedID: "products",
        getQuery: (item) => item.name,
        getURL: (item) => `/search?q=${item.name}`,
        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>`,
        },
      },
    ],
  });
  ```
</ParamField>

<ParamField body="showQuerySuggestions" type="object">
  Configures the query suggestions feature.

  When `feeds` is set, reference the suggestions feed with `feedID` instead of `indexName`.

  * `indexName`: the name of the index to query for suggestions.
  * `feedID`: the ID of the suggestions feed in the composition response. Use this property when `feeds` is set. It replaces `indexName`.
  * `getURL`: update the URL to send the search request.
  * `templates`: the [templates](#templates) to use for the suggestions.
  * `cssClasses`: CSS classes to customize the appearance.
    * `root`: the index section root element.
    * `list`: the list of results.
    * `header`: the section header.
    * `item`: each result item.
    * `noResults`: the no results element.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    showQuerySuggestions: {
      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>`,
      },
    },
  });
  ```
</ParamField>

<ParamField body="showPromptSuggestions" type="object">
  Configures the prompt suggestions feature.
  Shows prompt suggestions from a separate <Index />.
  When users select a suggestion,
  it's sent to a [Chat](/doc/api-reference/widgets/chat/js) widget in the same index.

  When `feeds` is set, reference the prompt suggestions feed with `feedID` instead of `indexName`.

  * `indexName`: the name of the index to query for prompt suggestions.
  * `feedID`: the ID of the suggestions feed in the composition response. Use this property when `feeds` is set. It replaces `indexName`.
  * `getURL`: a function that returns the URL to open when a user selects a prompt suggestion.
  * `templates`: the [templates](#templates) to use for the prompt suggestions.
  * `cssClasses`: CSS classes to customize the appearance.
    * `root`: the index section root element.
    * `list`: the list of results.
    * `header`: the section header.
    * `item`: each result item.
    * `noResults`: the no results element.
  * `searchParameters`: additional [search parameters](/doc/api-reference/api-parameters/) to send with the request when `indices` is set.

  <Note>
    To open the chat and send messages, `showPromptSuggestions` requires a `chat()` widget in the same index.
  </Note>

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    showPromptSuggestions: {
      indexName: "prompt_suggestions",
      templates: {
        header: ({ items }, { html }) =>
          html`Ask me anything (${items.length} suggestions)`,
        item: ({ item, onSelect }, { html }) =>
          html`<div onClick=${onSelect}>${item.prompt}</div>`,
      },
    },
  });
  ```
</ParamField>

<ParamField body="showRecent" type="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](#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.
    * `root`: the index section root element.
    * `list`: the list of results.
    * `header`: the section header.
    * `item`: each result item.
    * `noResults`: the no results element.

  ```js JavaScript icon=code theme={"system"}
  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>`,
      },
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="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.

  ```js JavaScript icon=code theme={"system"}
  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(),
            },
          },
        })),
      }));
    },
  });
  ```
</ParamField>

<ParamField body="searchParameters" type="object">
  Additional [search parameters](/doc/api-reference/api-parameters/) to send with the search request for every index.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    searchParameters: {
      hitsPerPage: 5,
    },
  });
  ```
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#style-your-widgets)
  and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com)
  or [Tailwind CSS](https://tailwindcss.com).

  **Root and detached shell:**

  * `root`: the widget's root element.
  * `detachedOverlay`: the detached overlay backdrop.
  * `detachedContainer`: the detached container.
  * `detachedFormContainer`: the detached form container.
  * `detachedSearchButton`: the detached search button.
  * `detachedSearchButtonIcon`: the detached search button icon wrapper.
  * `detachedSearchButtonSearchIcon`: the detached search button search icon.
  * `detachedSearchButtonPlaceholder`: the detached search button placeholder.
  * `detachedSearchButtonQuery`: the detached search button query.
  * `detachedSearchButtonClear`: the detached search button clear button.
  * `detachedSearchButtonClearIcon`: the detached search button clear icon.

  **Panel:**

  * `panel`: the panel root element.
  * `panelOpen`: the panel root element when open.
  * `panelLayout`: the panel layout element.

  **Search form:**

  * `form`: the search form.
  * `inputWrapperPrefix`: the input prefix area (contains submit button and loading indicator).
  * `backButton`: the back button (detached mode).
  * `backButtonIcon`: the back button icon.
  * `label`: the submit label.
  * `submitButton`: the submit button.
  * `submitButtonIcon`: the submit button icon.
  * `loadingIndicator`: the loading indicator.
  * `loadingIndicatorIcon`: the loading indicator icon.
  * `inputWrapper`: the input wrapper.
  * `input`: the search input.
  * `inputWrapperSuffix`: the input suffix area (contains reset button and AI mode button).
  * `resetButton`: the reset/clear button.
  * `resetButtonIcon`: the reset/clear button icon.
  * `aiModeButton`: the AI mode button.
  * `aiModeButtonIcon`: the AI mode button icon.
  * `aiModeButtonLabel`: the AI mode button label.

  Each source (`indices`, `showQuerySuggestions`, `showPromptSuggestions`, `showRecent`) also accepts its own `cssClasses` for styling result items. See their respective options for details.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    cssClasses: {
      root: "MyCustomAutocomplete",
      form: "MyCustomAutocompleteForm",
      input: "MyCustomAutocompleteInput",
      submitButton: "MyCustomAutocompleteSubmit",
      resetButton: "MyCustomAutocompleteReset",
      panel: "MyCustomAutocompletePanel",
    },
  });
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default="true">
  Whether to escape HTML in the item templates.
  Set this to `false` only if you fully trust your data and templates.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    escapeHTML: false,
  });
  ```
</ParamField>

<ParamField body="onSelect" type="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

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    onSelect({ query, setQuery, url }) {
      if (inSearchPage && !url) {
        setQuery(query);
        return;
      }
      
      window.location.href = url || `/search?q=${query}`;
    },
  });
  ```
</ParamField>

<ParamField body="getSearchPageURL" type="function">
  A function that returns the URL of the search page for a given search state.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    getSearchPageURL(nextUiState) {
      return `/search?q=${qs.stringify(nextUiState)}`;
    },
  });
  ```
</ParamField>

<ParamField body="placeholder" type="string">
  Placeholder text for the search input.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    placeholder: "Search for products...",
  });
  ```
</ParamField>

<ParamField body="autofocus" type="boolean" default="false">
  Whether to focus the input and open the panel by default.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    autofocus: true,
  });
  ```
</ParamField>

<ParamField body="detachedMediaQuery" type="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. In detached mode, the search form shows a back button (`.ais-AutocompleteBackButton`) to close the overlay.

  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.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    detachedMediaQuery: "(max-width: 768px)",
  });

  // Disable detached mode
  EXPERIMENTAL_autocomplete({
    // ...
    detachedMediaQuery: "",
  });
  ```
</ParamField>

<ParamField body="translations" type="object">
  Text labels for detached mode controls.

  * `detachedCancelButtonText`: label for the detached cancel button.
  * `detachedSearchButtonTitle`: title for the detached search button.
  * `detachedClearButtonTitle`: title for the detached clear button.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    translations: {
      detachedCancelButtonText: "Close",
      detachedSearchButtonTitle: "Search",
      detachedClearButtonTitle: "Reset",
    },
  });
  ```
</ParamField>

<ParamField body="aiMode" type="boolean" default="false">
  Whether to show an AI Mode button in the search input.
  When users click this button, it opens the [Chat](/doc/api-reference/widgets/chat/js) widget and sends the current query.

  To use this option, add a `chat()` widget on the same index.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    aiMode: true,
  });
  ```
</ParamField>

## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="panel" type="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`, `suggestions`, and `promptSuggestions`, if applicable.
  * `indices`: an array containing the data for each index.

  ```js JavaScript icon=code theme={"system"}
  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>
      `,
    },
  });
  ```
</ParamField>

<ParamField body="indices[*].templates.header" type="function">
  The template to use for the header, before the list of items for that index.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    indices: [
      {
        // ...
        templates: {
          header: ({ items }, { html }) => {
            return html`<div>Products (${items.length} results)</div>`;
          }
        },
      },
    ],
  });
  ```
</ParamField>

<ParamField body="indices[*].templates.item" type="function">
  The template to use for each item that is returned by the search query on that index.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    indices: [
      {
        // ...
        templates: {
          item: ({ item, onSelect }, { html, components }) => {
            return html`<div onClick=${onSelect}>
              ${components.ReverseHighlight({ hit: item, attribute: 'name' })}
            </div>`;
          }
        },
      },
    ],
  });
  ```
</ParamField>

<ParamField body="indices[*].templates.noResults" type="function">
  The template to use when an index returns no results.
  If an index defines a `noResults` template,
  the panel stays visible even when all indices return no results,
  so you can display a helpful message.

  ```js JavaScript icon=code theme={"system"}
  EXPERIMENTAL_autocomplete({
    // ...
    indices: [
      {
        // ...
        templates: {
          noResults: (_, { html }) => {
            return html`<div>No results found. Try a different query.</div>`;
          }
        },
      },
    ],
  });
  ```
</ParamField>