This widget is and is subject to change in minor versions.
You are viewing the documentation for InstantSearch.js v4 .
To upgrade from v3, see the migration guide .
Looking for the v3 version of this page?
View the v3 docs . EXPERIMENTAL_autocomplete ({ container: string | HTMLElement ; // Optional parameters indices ?: array , showSuggestions? : object , onSelect? : function , getSearchPageURL ?: function , searchParameters ?: object , templates ?: object , cssClasses ?: object , }) Import import { EXPERIMENTAL_autocomplete } from "instantsearch.js/es/widgets" ;
The autocomplete widget 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 “showSuggestions” feature that displays query suggestions from a separate index.
Examples EXPERIMENTAL_autocomplete ({ container: '#autocomplete' , showSuggestions: { indexName: 'query_suggestions' , getURL : ( item ) => `/search?q= ${ item . query } ` , }, indices: [ { indexName: 'instant_search' , getQuery : ( item ) => item . name , getUrl : ( item ) => `/search?q= ${ item . name } ` , templates: { header : ( _ , { html }) => html `<div>Products</div>` , item : ({ item , onSelect }, { html }) => html `<div onClick= ${ onSelect } > ${ item . name } </div>` , }, }, ], }) Options container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into. EXPERIMENTAL_autocomplete ({ container: "#autocomplete" , });
An array of objects that define the indices to query and how to display the results.
indexName: the name of the index to querygetQuery: preprocess the query before it is sent for searchgetUrl: update the url to send the search requestsearchParameters: additional search parameters to send with the search requesttemplates: the templates to use for the index EXPERIMENTAL_autocomplete ({ indices: [ { indexName: "instant_search" , getQuery : ( item ) => item . name , getUrl : ( item ) => `/search?q= ${ item . name } ` , searchParameters: { hitsPerPage: 5 , }, templates: { header : ({ items }, { html }) => html `<div>Products ( ${ items . length } results)</div>` , item : ({ item , onSelect }, { html , components }) => html `<div onClick= ${ onSelect } > ${ components . ReverseHighlight ({ hit: item , attribute: 'name' }) } </div>` , }, }, ], }); Configures the query suggestions feature.
indexName: the name of the index to query for suggestionsgetURL: update the url to send the search requesttemplates: the templates to use for the suggestions EXPERIMENTAL_autocomplete ({ // ... showSuggestions: { indexName: "query_suggestions" , getURL : ( item ) => `/search?q= ${ item . query } ` , templates: { header : ({ items }, { html }) => html `Suggestions ( ${ items . length } results)` , item : ({ item , onSelect }, { html , components }) => html `<div onClick= ${ onSelect } > ${ components . ReverseHighlight ({ hit: item , attribute: 'query' }) } </div>` , }, }, }); Additional search parameters to send with the search request for every index. EXPERIMENTAL_autocomplete ({ // ... searchParameters: { hitsPerPage: 5 , }, }); The templates to use for the widget. EXPERMENTAL_autocomplete ({ // ... templates: { // ... }, }); The CSS classes you can override :
root. The widget’s root element.list. The list of results.item. The list of items. EXPERIMENTAL_autocomplete ({ // ... cssClasses: { root: "MyCustomAutocomplete" , list: [ "MyCustomAutocompleteList" , "MyCustomAutocompleteList--subclass" ], item: "MyCustomAutocompleteItem" }, }); The templates to use for the widget. EXPERIMENTAL_autocomplete ({ // ... templates: { // ... }, }); 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
EXPERIMENTAL_autocomplete ({ // ... onSelect ({ query , setQuery , url }) { if ( inSearchPage && ! url ) { setQuery ( query ); return ; } window . location . href = url || `/search?q= ${ query } ` ; }, }); A function that returns the URL of the search page for a given search state. EXPERIMENTAL_autocomplete ({ // ... getSearchPageURL ( nextUiState ) { return `/search?q= ${ qs . stringify ( nextUiState ) } ` ; }, }); Templates You can customize parts of a widget’s UI using the Templates API.
Each template includes an html function,
which you can use as a tagged template .
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see Templating your UI .
The html function is available in InstantSearch.js version 4.46.0 or later.
Use the template option to customize how the panel is rendered.
This is useful when implementing layouts with multiple rows or columns. The template receives an object containing:
elements: a key-value dictionary of indices to render. These include regular index names, and special elements like recent and suggestions, if applicable.indices: an array containing the data for each index. EXPERIMENTAL_autocomplete ({ // ... templates: { panel : ({ elements , indices }, { html }) => html ` <div> <p>My custom panel</p> <div class="left"> ${ elements . suggestions } </div> <div class="right"> ${ elements . instant_search } </div> </div> ` , }, }); The template to use for the header, before the list of items for that index. EXPERIMENTAL_autocomplete ({ // ... indices: [ { // ... templates: { header : ({ items }, { html }) => { return html `<div>Products ( ${ items . length } results)</div>` ; } }, }, ], }); indices[*].templates.item
The template to use for each item that is returned by the search query on that index. EXPERIMENTAL_autocomplete ({ // ... indices: [ { // ... templates: { item : ({ item , onSelect }, { html , components }) => { return html `<div onClick= ${ onSelect } > ${ components . ReverseHighlight ({ hit: item , attribute: 'name' }) } </div>` ; } }, }, ], }); 
