Skip to main content
The createAutocomplete function returns methods to help you create an autocomplete experience from scratch. This is fully headless: you’re in charge of creating your own autocomplete renderer.
Building a custom renderer is an advanced pattern. You don’t need it unless you’ve reached limitations with autocomplete-js and its templating capabilities.

​
Installation

First, you need to install the package. 
npm install @algolia/autocomplete-core
Then import it in your project:
JavaScript
import { createAutocomplete } from "@algolia/autocomplete-core";
If you don’t use a package manager, you can use the HTML script element:
HTML
<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@1.19.4/dist/umd/index.production.js"
  integrity="kBu6+uqPkzse3Xwdtu+lgVEldgpafG46IuNEmoOBtFw="
  crossorigin="anonymous"
></script>
<script>
  const { createAutocomplete } = window["@algolia/autocomplete-core"];
</script>

​
Example

This example uses the package along with the algoliasearch API client and getAlgoliaResults function from the Autocomplete Algolia preset. It returns a set of functions to build an autocomplete experience.
JavaScript
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { createAutocomplete } from "@algolia/autocomplete-core";
import { getAlgoliaResults } from "@algolia/autocomplete-preset-algolia";

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

const autocomplete = createAutocomplete({
  getSources() {
    return [
      {
        sourceId: "querySuggestions",
        getItemInputValue: ({ item }) => item.query,
        getItems({ query }) {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search_demo_query_suggestions",
                params: {
                  query,
                  hitsPerPage: 4,
                },
              },
            ],
          });
        },
      },
    ];
  },
});

​
Parameters

​
getSources
The sources to get the collections from.
​
reshape
Reshape
The function called to reshape the sources after they’re resolved.This is useful to transform sources before rendering them. You can group sources by attribute, remove duplicates, create shared limits between sources, etc.See Reshaping sources for more information.
TypeScript
type Reshape = (params: {
  sources: AutocompleteReshapeSource[];
  sourcesBySourceId: Record<string, AutocompleteReshapeSource>;
  state: AutocompleteState;
}) => AutocompleteReshapeSource[];
​
insights
boolean | InsightsPluginOptions
default:false
Whether to enable the Algolia Insights plugin.This option accepts an object to configure the plugin. You can see the available options in the plugin’s documentation.If you don’t pass an insightsClient, it will be automatically detected from the window object, or downloaded from the jsDelivr CDN.If you manually enable the Insights plugin, this option won’t have any effect.
​
id
string
An ID for the autocomplete to create accessible attributes.
​
onStateChange
(params: { state: AutocompleteState<TItem> }) => void
The function called when the internal state changes.
​
enterKeyHint
"enter" | "done" | "go" | "next" | "previous" | "search" | "send"
since: v1.10.0
The action label or icon to present for the enter key on virtual keyboards.
​
ignoreCompositionEvents
boolean
default:false
since: v1.15.1
Whether to update the search input value in the middle of a composition session. This is useful when users need to search using non-latin characters.
​
placeholder
string
The placeholder text to show in the search input when there’s no query.
​
autoFocus
boolean
default:false
Whether to focus the search input or not when the page is loaded.
​
defaultActiveItemId
number | null
default: null
The default item index to pre-select.You should use 0 when the autocomplete is used to open links, instead of triggering a search in an application.
​
openOnFocus
boolean
default:false
Whether to open the panel on focus when there’s no query.
​
stallThreshold
number
default:300
How many milliseconds must elapse before considering the autocomplete experience stalled.
​
initialState
Partial<AutocompleteState>
The initial state to apply when autocomplete is created.
​
environment
typeof window
default: window
The environment in which your application is running.This is useful if you’re using autocomplete in a different context than window.
​
navigator
Navigator
An implementation of Autocomplete’s Navigator API to redirect users when opening a link.Learn more on the Navigator API documentation.
​
shouldPanelOpen
(params: { state: AutocompleteState }) => boolean
The function called to determine whether the panel should open or not.By default, the panel opens when there are items in the state.
​
onSubmit
(params: { state: AutocompleteState, event: Event, ...setters }) => void
The function called when submitting the Autocomplete form.
​
onReset
(params: { state: AutocompleteState, event: Event, ...setters }) => void
The function called when resetting the Autocomplete form.
​
debug
boolean
default:false
A flag to activate the debug mode.This is useful while developing because it keeps the panel open even when the blur event occurs. Make sure to turn it off in production.See Debugging for more information.
​
plugins
The plugins that encapsulate and distribute custom Autocomplete behaviors.See Plugins for more information.

​
Returns

The createAutocomplete function returns prop getters, state setters, and a refresh method that updates the UI state with fresh sources.
JavaScript
const {
  getEnvironmentProps,
  getRootProps,
  getFormProps,
  getInputProps,
  getItemProps,
  getLabelProps,
  getListProps,
  setActiveItemId,
  setQuery,
  setCollections,
  setIsOpen,
  setStatus,
  setContext,
  refresh,
  update,
} = createAutocomplete(options);
The createAutocomplete function returns state setters and additional helpers:
​
refresh
() => Promise<void>
Updates the UI state with fresh sources. You must call this function whenever you mutate the state with setters and want to reflect the changes in the UI.
​
update
(updatedOptions: Partial<AutocompleteOptions>) => void
Updates the Autocomplete instance with new options.
​
destroy
() => void
Destroys the Autocomplete instance and removes it from the DOM.
⌘I