Autocomplete - Algolia

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

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<EXPERIMENTAL_Autocomplete
  indices={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

JavaScript

import { EXPERIMENTAL_Autocomplete } from "react-instantsearch";

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

Examples

JavaScript

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

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

JavaScript

<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>,
    },
  ]}
/>

showQuerySuggestions

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

JavaScript

<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>,
  }}
/>

showPromptSuggestions

object

Configures the prompt suggestions feature. Shows prompt suggestions from a separate . When users select a suggestion, it’s sent to a Chat widget in the same index.

indexName: the name of the index to query for prompt suggestions
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 to send with the request

To open the chat and send messages, showPromptSuggestions requires a Chat widget in the same index.

JavaScript

<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>
    ),
  }}
/>

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

JavaScript

<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>
    ),
  }}
/>

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) =>
    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,
  }}
/>

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)}`;
  }}
/>

panelComponent

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.

JavaScript

<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>
  )}
/>

classNames

object

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.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.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  classNames={{
    root: "MyCustomAutocomplete",
    form: "MyCustomAutocompleteForm",
    input: "MyCustomAutocompleteInput",
    submitButton: "MyCustomAutocompleteSubmit",
    resetButton: "MyCustomAutocompleteReset",
    panel: "MyCustomAutocompletePanel",
  }}
/>

placeholder

string

Placeholder text for the search input.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  placeholder="Search for products..."
/>

autoFocus

boolean

default:"false"

Whether to focus the input and open the panel by default.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  autoFocus={true}
/>

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

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  detachedMediaQuery="(max-width: 768px)"
/>

{/* Disable detached mode */}
<EXPERIMENTAL_Autocomplete
  // ...
  detachedMediaQuery=""
/>

translations

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.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  translations={{
    detachedCancelButtonText: "Close",
    detachedSearchButtonTitle: "Search",
    detachedClearButtonTitle: "Reset",
  }}
/>

aiMode

boolean

default:"false"

Whether to show an AI Mode button in the search input. When users click this button, it opens the Chat widget and sends the current query.To use this prop, add a <Chat> widget on the same index.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  aiMode={true}
/>

React InstantSearch

Documentation Index

​Import

​About this widget

​Examples

​Props

Import

About this widget

Examples

Props