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

# createAutocomplete

> This function returns methods to help you create an autocomplete experience from scratch.

<Tip>
  Autocomplete is also available as an experimental widget in InstantSearch,
  making it easier to integrate into your search experience.
  For more information,
  see the API reference for [InstantSearch.js](/doc/api-reference/widgets/autocomplete/js) or
  [React InstantSearch](/doc/api-reference/widgets/autocomplete/react).
</Tip>

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](/doc/ui-libraries/autocomplete/guides/creating-a-renderer).

<Note>
  Building a custom renderer is an advanced pattern.
  You don't need it unless you've reached limitations with
  [`autocomplete-js`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js)
  and its templating capabilities.
</Note>

## Installation

First, you need to install the package.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/autocomplete-core
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/autocomplete-core
  ```
</CodeGroup>

Then import it in your project:

```js JavaScript icon=code theme={"system"}
import { createAutocomplete } from "@algolia/autocomplete-core";
```

If you don't use a package manager, you can use the HTML `script` element:

```html HTML icon=code-xml theme={"system"}
<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@1.19.9/dist/umd/index.production.js"
  integrity="sha256-hGtahorLTfXp7EDEI+EE4sleK5RkW70Bdr/YCKMxgVY="
  crossorigin="anonymous"
></script>
<script>
  const { createAutocomplete } = window["@algolia/autocomplete-core"];
</script>
```

## Example

This example uses the package along with the [`algoliasearch`](https://www.npmjs.com/package/algoliasearch)
API client and [`getAlgoliaResults`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-preset-algolia/getAlgoliaResults)
function from the Autocomplete Algolia preset.
It returns [a set of functions](#returns) to build an autocomplete experience.

```js JavaScript icon=code theme={"system"}
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

<ParamField body="getSources">
  The [sources](/doc/ui-libraries/autocomplete/core-concepts/sources) to get the collections from.
</ParamField>

<ParamField body="reshape" type="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](/doc/ui-libraries/autocomplete/guides/reshaping-sources) for more information.

  ```ts TypeScript icon="code" theme={"system"}
  type Reshape = (params: {
    sources: AutocompleteReshapeSource[];
    sourcesBySourceId: Record<string, AutocompleteReshapeSource>;
    state: AutocompleteState;
  }) => AutocompleteReshapeSource[];
  ```
</ParamField>

<ParamField body="insights" type="boolean | InsightsPluginOptions" default={false}>
  Whether to enable the [Algolia Insights plugin](/doc/ui-libraries/autocomplete/api-reference/autocomplete-plugin-algolia-insights/createAlgoliaInsightsPlugin).

  This option accepts an object to configure the plugin.
  You can see the available options in the [plugin's documentation](/doc/ui-libraries/autocomplete/api-reference/autocomplete-plugin-algolia-insights/createAlgoliaInsightsPlugin/#parameters).

  If you don't pass an `insightsClient`,
  it will be automatically detected from the `window` object,
  or downloaded from the [jsDelivr CDN](https://www.jsdelivr.com).

  If you manually enable the Insights plugin, this option won't have any effect.
</ParamField>

<ParamField body="id" type="string" default="&#x22;autocomplete-0&#x22; (incremented for each instance)">
  An ID for the autocomplete to create accessible attributes.
</ParamField>

<ParamField body="onStateChange" type="(params: { state: AutocompleteState<TItem> }) => void">
  The function called when the internal state changes.
</ParamField>

<ParamField body="enterKeyHint" type="&#x22;enter&#x22; | &#x22;done&#x22; | &#x22;go&#x22; | &#x22;next&#x22; | &#x22;previous&#x22; | &#x22;search&#x22; | &#x22;send&#x22;" post={["since: v1.10.0"]}>
  The action label or icon to present for the enter key on virtual keyboards.
</ParamField>

<ParamField body="ignoreCompositionEvents" type="boolean" default={false} post={["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.
</ParamField>

<ParamField body="placeholder" type="string">
  The placeholder text to show in the search input when there's no query.
</ParamField>

<ParamField body="autoFocus" type="boolean" default={false}>
  Whether to focus the search input or not when the page is loaded.
</ParamField>

<ParamField body="defaultActiveItemId" type="number | null" post={["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.
</ParamField>

<ParamField body="openOnFocus" type="boolean" default={false}>
  Whether to open the panel on focus when there's no query.
</ParamField>

<ParamField body="stallThreshold" type="number" default={300}>
  How many milliseconds must elapse before considering the autocomplete experience [stalled](/doc/ui-libraries/autocomplete/core-concepts/state/#param-status).
</ParamField>

<ParamField body="initialState" type="Partial<AutocompleteState>">
  The initial state to apply when autocomplete is created.
</ParamField>

<ParamField body="environment" type="typeof window" post={["default: window"]}>
  The environment in which your application is running.

  This is useful if you're using autocomplete in a different context than `window`.
</ParamField>

<ParamField body="navigator" type="Navigator">
  An implementation of Autocomplete's Navigator API to redirect users when opening a link.

  Learn more on the [Navigator API](/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation) documentation.
</ParamField>

<ParamField body="shouldPanelOpen" type="(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.
</ParamField>

<ParamField body="onSubmit" type="(params: { state: AutocompleteState, event: Event, ...setters }) => void">
  The function called when submitting the Autocomplete form.
</ParamField>

<ParamField body="onReset" type="(params: { state: AutocompleteState, event: Event, ...setters }) => void">
  The function called when resetting the Autocomplete form.
</ParamField>

<ParamField body="debug" type="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](/doc/ui-libraries/autocomplete/guides/debugging) for more information.
</ParamField>

<ParamField body="plugins">
  The plugins that encapsulate and distribute custom Autocomplete behaviors.

  See [Plugins](/doc/ui-libraries/autocomplete/core-concepts/plugins) for more information.
</ParamField>

## Returns

The `createAutocomplete` function returns prop getters,
[state setters](/doc/ui-libraries/autocomplete/core-concepts/state#setters),
and a `refresh` method that updates the UI state with fresh sources.

```js JavaScript icon=code theme={"system"}
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:

<ParamField body="refresh" type="() => 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.
</ParamField>

<ParamField body="update" type="(updatedOptions: Partial<AutocompleteOptions>) => void">
  Updates the Autocomplete instance with new options.
</ParamField>

<ParamField body="destroy" type="() => void">
  Destroys the Autocomplete instance and removes it from the DOM.
</ParamField>