API Reference / InstantSearch.js Widgets / instantsearch

instantsearch

Widget signature 
instantsearch({
  indexName: string,
  searchClient: object,
  // Optional parameters
  numberLocale: string,
  searchFunction: function,
  initialUiState: object,
  onStateChange: function,
  stalledSearchDelay: number,
  routing: boolean|object,
  insightsClient: function,
});
See code examples

About this widget

You are currently reading the documentation for InstantSearch.js V4. Read our migration guide to learn how to upgrade from V3 to V4. You can still access the V3 documentation for this page.

The instantsearch object is the main component of InstantSearch.js. It manages the widget and lets you add new ones.

Two parameters are required to get you started with InstantSearch.js:

  • indexName: the main index that you need to use for your new search UI
  • searchClient: the search client to plug to InstantSearch.js

The search client provided by Algolia needs an appId and an apiKey. Those parameters can be found in your Algolia dashboard.

To get up and running quickly with InstantSearch.js, have a look at the getting started guide.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const search = instantsearch({
  indexName: 'instant_search',
  searchClient: algoliasearch(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
  ),
});

// Add widgets
// ...

search.start();

Options

indexName
type: string
Required

The main index to search into.
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  indexName: 'instant_search',
});
searchClient
type: object
Required

Provides a search client to instantsearch. To implement a custom search client, take a look at a the custom back-end guide.
Copy 
1
2
3
4
5
6
7

const search = instantsearch({
  // ...
  searchClient: algoliasearch(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
  ),
});
numberLocale
type: string
Optional

The locale used to display numbers. This is passed to Number.prototype.toLocaleString().
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  numberLocale: 'fr',
});
searchFunction
type: function
Optional

A hook that is called each time a search needs to be done, with the helper as a parameter. It’s your responsibility to call helper.search(). This option allows you, for example, to avoid doing searches at page load.

When modifying the state of the helper within searchFunction, the helper automatically reset the page to 0. If you want to keep the current page, you need to store the information about the page, modify the state and reapply the pagination.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

const search = instantsearch({
  // ...
  searchFunction(helper) {
    if (helper.state.query) {
      helper.search();
    }
  },
});


// Example which avoids the page to be reset to 0
const search = instantsearch({
  // ...
  searchFunction(helper) {
    const page = helper.getPage(); // Retrieve the current page

    helper.setQuery('Hello') // this call resets the page
          .setPage(page) // we re-apply the previous page
          .search();
  }
});
initialUiState
type: object
Optional

Adds a uiState to your instantsearch instance, which lets you provide an initial state to your widgets. To apply the uiState to the search parameters, you must add your widgets to your instantsearch instance.
Copy 
1
2
3
4
5
6
7
8
9

const search = instantsearch({
  // ...
  initialUiState: {
    indexName: {
      query: 'phone',
      page: 5,
    },
  },
});
onStateChange
type: function
Optional

Triggers when the state changes.

Whenever you start using this option, the instance becomes controlled. This means you become responsible of updating the UI state with setUiState.

This can be useful to perform custom logic whenever the state changes.
Copy 
1
2
3
4
5
6
7
8

const search = instantsearch({
  // ...
  onStateChange({ uiState, setUiState }) {
    // Custom logic

    setUiState(uiState);
  },
});
stalledSearchDelay
type: number
default: 200
Optional

How much time before a search is considered stalled. You can find more information in the slow network guide.
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  stalledSearchDelay: 500,
});
routing
type: boolean|object
default: false
Optional

The router configuration used to save the UI state into the URL, or any client-side persistence. You can find more information in the routing guide. The object form accepts two attributes:

  • router: object: this object saves the UI state. By default, it uses an instance of the history with the default parameters. It accepts:
    • onUpdate: function: adds an event listener that makes InstantSearch aware of external changes to the storage medium (e.g. the URL). Typically you’ll set up a listener for popstate, which triggers a callback with the current routeState.
    • read: function: reads the routing storage and gets routeState. It doesn’t take any parameters, and returns an object.
    • write: function: pushes routeState into a routing storage.
    • createURL: function: transforms routeState into a URL. It receives an object and returns a string (which may be empty).
    • dispose: function: cleans up all event listeners.
  • stateMapping: object: transforms the uiState into an object that can be saved by the router. The default value is provided by simple. It accepts:
    • stateToRoute: function: transforms a uiState representation into routeState. It receives an object that contains the UI state of all the widgets in the page. It can return any object that is readable by routeToState.
    • routeToState: function: transforms routeState into a uiState representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  routing: true,
});
insightsClient
type: function
Optional

The function exposed by the search-insights (usually window.aa). This is needed if you want to send click and conversion events with InstantSearch.
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  insightsClient: window.aa
});

Methods

addWidgets

Adds widgets to the instantsearch instance.

You can add widgets to instantsearch before and after you start it.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const search = instantsearch({
  // ...
});

const searchBox = instantsearch.widgets.searchBox({
  // ...
});

const hits = instantsearch.widgets.hits({
  // ...
});

search.addWidgets([searchBox, hits]);
addWidget

Adds a widget to the instantsearch instance.

You can add widgets to instantsearch before and after you start it.

This method is deprecated and is only supported until 4.x releases. Please use addWidgets([widget]) instead.
Copy 
1
2
3
4
5
6
7
8
9

const search = instantsearch({
  // ...
});

const searchBox = instantsearch.widgets.searchBox({
  // ...
});

search.addWidget(searchBox);
start

Finalizes the setup of instantsearch and triggers the first search.

You should call this method after you have added all your required widgets to instantsearch. You can also add widgets after instantsearch has started, but these widgets are not taken into account during searches made before you add them.
Copy 
1
2
3
4
5

const search = instantsearch({
  // ...
});

search.start();
removeWidgets

Removes widgets from the instantsearch instance. You can only do this after you start instantsearch.

The widgets you remove from instantsearch must implement a dispose() method to reset the search parameters they manage.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const search = instantsearch({
  // ...
});

const searchBox = instantsearch.widgets.searchBox({
  // ...
});

const hits = instantsearch.widgets.hits({
  // ...
});

search.removeWidgets([searchBox, hits]);
removeWidget

Removes a widget from the instantsearch instance. You can only do this after you start instantsearch.

The widget you remove from instantsearch must implement a dispose() method to reset the search parameters they manage.

This method is deprecated and is only supported until 4.x releases. Please use removeWidgets([widget]) instead.
Copy 
1
2
3
4
5
6
7
8
9

const search = instantsearch({
  // ...
});

const searchBox = instantsearch.widgets.searchBox({
  // ...
});

search.removeWidget(searchBox);
dispose

Removes all widgets from the instance. This methods doesn’t trigger a search.
Copy 
1
2
3
4
5

const search = instantsearch({
  // ...
});

search.dispose();
setUiState

Injects a uiState into the instance without relying on internal events (e.g., connectors’ refine or widget interactions).

For the UI state to work, the widgets responsible for each UI state attribute need to be mounted. For instance, a searchBox is necessary to provide a query.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const search = instantsearch({
  // ...
});

search.start();

search.setUiState({
  // Replace instant_search with your own index name
  instant_search: {
    query: 'phone'
  }
});
refresh

Clears the Algolia responses cache and triggers a new search.

You can find more details about caching in InstantSearch in our guide about caching.
Copy 
1
2
3
4
5

const search = instantsearch({
  // ...
});

search.refresh();

Events

render

Fires when all widgets are rendered. This happens after every search request.
Copy 
1
2
3
4
5
6
7

const search = instantsearch({
  // ...
});

search.on('render', () => {
  // Do something on render
});
error

Fires when calling the API reports an error.
Copy 
1
2
3
4
5
6
7

const search = instantsearch({
  // ...
});

search.on('error', ({ error }) => {
  // Do something on error
});

Did you find this page helpful?

InstantSearch.js v4