Instantsearch | InstantSearch.js V3 (Deprecated)

This version of InstantSearch.js has been deprecated in favor of the latest version of InstantSearch.js.

Signature

instantsearch({
  indexName: string,
  searchClient: object,
  // Optional parameters
  numberLocale: string,
  searchFunction: function,
  searchParameters: object,
  stalledSearchDelay: number,
  routing: boolean|object,
});

About this widget

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

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

The main index to search into.

1
2
3
4
const search = instantsearch({
  // ...
  indexName: 'instant_search',
});

searchClient

Provides a search client to instantsearch. To implement a custom search client, take a look at a the custom backend guide.

1
2
3
4
5
6
7
const search = instantsearch({
  // ...
  searchClient: algoliasearch(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
  ),
});

numberLocale

The locale used to display numbers. This is passed to Number.prototype.toLocaleString().

1
2
3
4
const search = instantsearch({
  // ...
  numberLocale: 'fr',
});

searchFunction

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.

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 avoid the page to be reseted 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();
  }
});

searchParameters

Additional search parameters to pass to the Algolia API. We recommend using the configure widget instead to provide additional search parameters to the API.

1
2
3
4
5
6
7
8
9
10
const search = instantsearch({
  // ...
  searchParameters: {
    hitsPerPage: 6,
    distinct: true,
    disjunctiveFacetsRefinements: {
      brand: ['Samsung', 'Apple']
    },
  },
});

stalledSearchDelay

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

1
2
3
4
const search = instantsearch({
  // ...
  stalledSearchDelay: 500,
});

routing

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 a route object. It doesn’t take any parameters, and returns an object.
  • write: function: pushes a route object into a routing storage. Takes the UI state from the state mapping.
  • createURL: function: transforms a route object 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 a route object. 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 a route object 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.

1
2
3
4
const search = instantsearch({
  // ...
  routing: true,
});

1
2
3
4
5
6
7
const search = instantsearch({
  // ...
  routing: {
    router: instantsearch.routers.history(),
    stateMapping: instantsearch.stateMappings.simple(),
  },
});

Methods

addWidget

Adds a widget. This can be done before and after instantsearch has been started. Adding a widget after instantsearch started is considered experimental and therefore possibly unstable. If you find anything, please open an issue.

This method is deprecated, and should be replaced with addWidgets([widget]).

1
2
3
4
5
6
7
8
9
const search = instantsearch({
  // ...
});

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

search.addWidget(searchBox);

addWidgets

Adds multiple widgets. This can be done before and after the instantsearch has been started. Adding widgets after instantsearch started is considered experimental and therefore possibly unstable. If you find anything, please open an issue.

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]);

start

Ends the initialization of instantsearch and triggers the first search. This method should be called after all widgets have been added to the instance of instantsearch. The instantsearch object also supports adding and removing widgets after the start, as an experimental feature.

1
2
3
4
5
const search = instantsearch({
  // ...
});

search.start();

removeWidget

Removes a widget. This can be done after the instantsearch has been started. Removing a widget after instantsearch started is considered experimental and therefore possibly unstable. If you find anything, please open an issue.

The widget instance to remove from instantsearch must implement a dispose() method to be properly removed.

This method is deprecated, and should be replaced with removeWidgets([widget]).

1
2
3
4
5
6
7
8
9
const search = instantsearch({
  // ...
});

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

search.removeWidget(searchBox);

removeWidgets

Removes multiple widgets. This can be done only after the instantsearch has been started. Removing widgets after instantsearch started is considered experimental and therefore possibly unstable. If you find anything, please open an issue.

The widgets instances to remove from instantsearch must implement a dispose() method to be properly removed.

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]);

dispose

Removes all widgets without triggering a search afterwards. This is an experimental feature. If you find an issue with it, please open an issue.

1
2
3
4
5
const search = instantsearch({
  // ...
});

search.dispose();

refresh

Clears the cached responses from Algolia and triggers a new search. You can find more information in the guide about caching.

1
2
3
4
5
const search = instantsearch({
  // ...
});

search.refresh();

Events

render

Triggered when the rendering of all the widgets is done. This happens after the search results comes back from Algolia, which means that it is triggered for the first time after all the widgets have been through all their lifecycle steps once (getConfiguration, init, render).

1
2
3
4
5
6
7
const search = instantsearch({
  // ...
});

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

error

Triggered when an error is reported when calling the API.

1
2
3
4
5
6
7
const search = instantsearch({
  // ...
});

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