autocomplete

This function creates a JavaScript autocomplete experience.

Example

HTML
<div id="autocomplete"></div>
JavaScript
import algoliasearch from 'algoliasearch/lite';
import {
autocomplete,
getAlgoliaHits,
} from '@francoischalifour/autocomplete-js';
const searchClient = algoliasearch(
'latency',
'6be0576ff61c053d5f9a3225e2a90f76'
);
const autocomplete = autocomplete({
container: '#autocomplete',
getSources() {
return [
{
getInputValue: ({ suggestion }) => suggestion.query,
getSuggestions({ query }) {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'instant_search_demo_query_suggestions',
query,
params: {
hitsPerPage: 4,
},
},
],
});
},
},
];
},
});

Reference

autocomplete accepts all the props that createAutocomplete supports.

container

string | HTMLElement | required

The container for the autocomplete search box. You can either pass a CSS selector or an Element. The first element matching the provided selector will be used as container.

getSources

required

The sources to get the suggestions from.

id

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

The autocomplete ID to create accessible attributes.

onStateChange

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

Function called when the internal state changes.

placeholder

string

The text that appears in the search box input when there is no query.

autoFocus

boolean | defaults to false

Whether to focus the search box when the page is loaded.

defaultHighlightedIndex

number | null | default to null

The default item index to pre-select.

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

enableCompletion

boolean | defaults to false

Whether to show the highlighted suggestion as completion in the input.

openOnFocus

boolean | defaults to false

Whether to open the dropdown on focus when there's no query.

stallThreshold

number | defaults to 300

The number of milliseconds that must elapse before the autocomplete experience is stalled.

initialState

Partial<AutocompleteState>

The initial state to apply when autocomplete is created.

environment

typeof window | defaults to window

The environment from where your JavaScript is running.

Useful if you're using autocomplete in a different context than window.

navigator

Navigator

Navigator API to redirect the user when a link should be opened.

Learn more on the Navigator API documentation.

shouldDropdownShow

(params: { state: AutocompleteState }) => boolean

The function called to determine whether the dropdown should open.

By default, it opens when there are suggestions in the state.

onSubmit

(params: { state: AutocompleteState, event: Event, ...setters }) => void

The function called when the autocomplete form is submitted.

onInput

(params: {query: string, state: AutocompleteState, ...setters }) => void

The function called when the input changes.

This turns the experience in controlled mode, leaving you in charge of updating the state.

render

(params: { root: HTMLElement, sections: HTMLElement[], state: AutocompleteState<TItem> }) => void

Function called to render the autocomplete results. It is useful for rendering sections in different row or column layouts.

The default implementation appends all the sections to the root:

autocomplete({
// ...
render({ root, sections }) {
for (const section of sections) {
root.appendChild(section);
}
},
});

Returned props

const {
setHighlightedIndex,
setQuery,
setSuggestions,
setIsOpen,
setStatus,
setContext,
refresh,
} = autocomplete(options);

autocomplete returns all the state setters and refresh method that updates the UI state.

These setters are useful to control the autocomplete experience from external events.

Edit this page