createAutocomplete

Autocomplete Core exposes primitives to build an autocomplete experience.

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.

info

Building a custom renderer is an advanced pattern. You likely don't need it unless you've reached limitations with autocomplete-js and its templating capabilities.

Installation#

First, you need to install the package.

yarn add @algolia/autocomplete-core@alpha
# or
npm install @algolia/autocomplete-core@alpha

Then import it in your project:

import { createAutocomplete } from '@algolia/autocomplete-core';

If you don't use a package manager, you can use a standalone endpoint:

<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@alpha"></script>

Example#

This example uses the package along with the algoliasearch API client and getAlgoliaHits function from the Autocomplete Algolia preset. It returns a set of functions to build an autocomplete experience.

import algoliasearch from 'algoliasearch/lite';
import { createAutocomplete } from '@algolia/autocomplete-core';
import { getAlgoliaHits } from '@algolia/autocomplete-preset-algolia';
const searchClient = algoliasearch(
'latency',
'6be0576ff61c053d5f9a3225e2a90f76'
);
const autocomplete = createAutocomplete({
getSources() {
return [
{
sourceId: 'querySuggestionsSource',
getItemInputValue: ({ item }) => item.query,
getItems({ query }) {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'instant_search_demo_query_suggestions',
query,
params: {
hitsPerPage: 4,
},
},
],
});
},
},
];
},
});

Parameters#

getSources#

required

The sources to get the collections from.

id#

string | defaults to "autocomplete-0" (incremented for each instance)

An ID for the autocomplete to create accessible attributes.

onStateChange#

(params: { state: AutocompleteState<TItem> }) => void

The function called when the internal state changes.

placeholder#

string

The placeholder text to show in the search input when there's no query.

autoFocus#

boolean | defaults to false

Whether to focus the search input or not when the page is loaded.

defaultActiveItemId#

number | null | default to null

The default item index to pre-select.

We recommend using 0 when the query typed aims at opening item links, without triggering an actual search.

openOnFocus#

boolean | defaults to false

Whether to open the panel on focus or not when there's no query.

stallThreshold#

number | defaults to 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 | defaults to 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 the user 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 | defaults to 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 disable it in production.

See Debugging for more information.

Returns#

The createAutocomplete function returns prop getters, state setters, and a refresh method that updates the UI state.

const {
getEnvironmentProps,
getRootProps,
getFormProps,
getInputProps,
getItemProps,
getLabelProps,
getListProps,
setActiveItemId,
setQuery,
setCollections,
setIsOpen,
setStatus,
setContext,
refresh,
} = createAutocomplete(options);
Edit this page