> ## 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>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

```tsx Signature theme={"system"}
<EXPERIMENTAL_Autocomplete
  indices={array}
  feeds={array}
  showQuerySuggestions={object}
  showPromptSuggestions={object}
  showRecent={boolean | object}
  transformItems={function}
  onSelect={function}
  getSearchPageURL={function}
  searchParameters={object}
  panelComponent={function}
  classNames={object}
  placeholder={string}
  autoFocus={boolean}
  detachedMediaQuery={string}
  translations={object}
  aiMode={boolean}
/>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { EXPERIMENTAL_Autocomplete } from "react-instantsearch";
```

## About this widget

`<Autocomplete>` 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 JavaScript icon=code theme={"system"}
import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, Autocomplete } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <EXPERIMENTAL_Autocomplete
        indices={[
          {
            indexName: "instant_search",
            getQuery: (item) => item.name,
            getURL: (item) => `/search?q=${item.name}`,
            headerComponent: () => <div>Products</div>,
            itemComponent: ({ item, onSelect }) =>
              <div onClick={onSelect}>{item.name}</div>,
          },
        ]}
        showQuerySuggestions={{
          indexName: "query_suggestions",
        }}
      />
    </InstantSearch>
  );
}
```

## Props

<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
  * `headerComponent`: component to render for the header of the index
  * `itemComponent`: component to render for each result from a query
  * `noResultsComponent`: component to render when no results are found for the index
  * `classNames`: 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: (query) => query,
        getURL: (item) => `/search/?q=${item.query}`,
        searchParameters: {
          hitsPerPage: 5,
        },
        headerComponent: ({ items }) =>
          <div>Products ({items.length} results)</div>,
        itemComponent: ({ item, onSelect }) =>
          <div onClick={onSelect}>{item.name}</div>,
        noResultsComponent: () =>
          <div>No results found. Try a different query.</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` props are mutually exclusive.
  To use `feeds`, you need a composition-based `<InstantSearch>` (the `compositionID` prop must be set). See the [`Feeds`](/doc/api-reference/widgets/feeds/react) 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.
  * `headerComponent`: component to render for the header of the feed.
  * `itemComponent`: component to render for each result in the feed.
  * `noResultsComponent`: component to render when the feed returns no results.
  * `classNames`: 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.

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    feeds={[
      {
        feedID: "products",
        getQuery: (item) => item.name,
        getURL: (item) => `/search?q=${item.name}`,
        headerComponent: ({ items }) =>
          <div>Products ({items.length} results)</div>,
        itemComponent: ({ item, onSelect }) =>
          <div onClick={onSelect}>{item.name}</div>,
        noResultsComponent: () =>
          <div>No results found. Try a different query.</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.
  * `headerComponent`: component to render for the header of the index.
  * `itemComponent`: component to render for each suggestion.
  * `classNames`: 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}`,
      headerComponent: ({ items }) =>
        <div>Suggestions ({items.length} results)</div>,
      itemComponent: ({ item, onSelect }) =>
        <div onClick={onSelect}>{item.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/react) 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.
  * `headerComponent`: component to render for the header of the prompt suggestions.
  * `itemComponent`: component to render for each prompt suggestion (receives `item` with a `prompt` field and an optional `label` field, and `onSelect`).
  * `classNames`: 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>

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    // ...
    showPromptSuggestions={{
      indexName: "prompt_suggestions",
      headerComponent: ({ items }) => (
        <div>Ask me anything ({items.length} suggestions)</div>
      ),
      itemComponent: ({ item, onSelect }) => (
        <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`)
  * `headerComponent`: component to render for the header above the recent searches list
  * `itemComponent`: component to render for each recent search item (receives `item`, `onSelect`, and `onRemoveRecentSearch` props)
  * `classNames`: 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.

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    // ...
    showRecent={true}
  />

  {/* With customization */}
  <EXPERIMENTAL_Autocomplete
    // ...
    showRecent={{
      storageKey: 'my-app-recent-searches',
      headerComponent: ({ items }) => (
        <div>Recent Searches</div>
      ),
      itemComponent: ({ item, onSelect, onRemoveRecentSearch }) => (
        <div>
          <button onClick={onSelect}>{item.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.

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    // ...
    transformItems={(indices) =>
      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="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

  ```jsx 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.

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

<ParamField body="panelComponent" type="function">
  Use the component to customize how the panel is rendered.
  This is useful when implementing layouts with multiple rows or columns.

  The component receives a prop 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.

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    // ...
    panelComponent={({ elements, indices }) => (
      <div>
        <p>My custom panel</p>
        <div className="left">{elements.suggestions}</div>
        <div className="right">{elements.instant_search}</div>
      </div>
    )}
  />
  ```
</ParamField>

<ParamField body="classNames" type="object">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react/#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 `classNames` for styling result items. See their respective options for details.

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

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

  ```jsx 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.

  ```jsx 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.

  ```jsx 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.

  ```jsx 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/react) widget and sends the current query.

  To use this prop, add a `<Chat>` widget on the same index.

  ```jsx JavaScript icon=code theme={"system"}
  <EXPERIMENTAL_Autocomplete
    // ...
    aiMode={true}
  />
  ```
</ParamField>