API Reference / InstantSearch.js Widgets / instantsearch
Apr. 24, 2019

instantsearch

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

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

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 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
type: object
Optional

Additional search parameters to pass to the Algolia API. We recommend using the configure widget instead to provide additional search parameters to the API.
Copy 
1
2
3
4
5
6
7
8
9
10

const search = instantsearch({
  // ...
  searchParameters: {
    hitsPerPage: 6,
    distinct: true,
    disjunctiveFacetsRefinements: {
      brand: ['Samsung', 'Apple']
    },
  },
});
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 is the part that saves the UI state. By default, it uses an instance of the HistoryRouter with the default parameters. It accepts:
    • onUpdate: function: add an event listener to make InstantSearch aware of external changes to the storage medium (e.g. the URL) that aren’t done by InstantSearch. Typically you set up a listener for popstate, in which you call the callback with the current routeState.
    • read: function: reads the storage and gets a route object. It doesn’t take any parameters, and returns an object.
    • write: function: pushes a route object into a storage. Takes the UI state mapped by the state mapping configured in the 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 UI state into the object that is saved by the router. It accepts:
    • stateToRoute: function: transforms a UI state representation into a route object. It receives an object that contains the UI state of all the widgets in the page. It returns an object of any form as long as this form can be read by the routeToState.
    • routeToState: function: transforms route object into a UI state representation. It receives an object that contains the UI state stored by the router. The format is the output of stateToRoute.
Copy 
1
2
3
4

const search = instantsearch({
  // ...
  routing: true,
});

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.
Copy 
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.
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]);
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.
Copy 
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.
Copy 
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.
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]);
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.
Copy 
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.
Copy 
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).
Copy 
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.
Copy 
1
2
3
4
5
6
7

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

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

Did you find this page helpful?

InstantSearch.js v3