Edit this page


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

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

  • appId: your algolia application id
  • apiKey: the search key associated with your application
  • indexName: the main index that you will use for your new search UI

Those parameters can be found in your Algolia dashboard. If you want to get up and running quickly with InstantSearch.js, have a look at the getting started.


const search = instantsearch({ 
  appId: string, 
  apiKey: string, 
  indexName: string, 
  numberLocale: [string], 
  searchFunction: [function], 
  createAlgoliaClient: [function], 
  searchParameters: [object], 
  urlSync: [boolean|UrlSyncOptions], 
  stalledSearchDelay: [number], 
  routing: [RoutingOptions], 
  searchClient: [SearchClient], 
}: InstantSearchOptions);

search.addWidget(/* A widget instance here */);



  • appIdstring

    The Algolia application ID

  • apiKeystring

    The Algolia search-only API key

  • indexNamestring

    The name of the main index

  • numberLocale[string]

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

  • searchFunction[function]

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

  • createAlgoliaClient[function]

    Deprecated in favor of searchClient.

    Allows you to provide your own algolia client instead of the one instantiated internally by instantsearch.js. Useful in situations where you need to setup complex mechanism on the client or if you need to share it easily.


      // other parameters
      createAlgoliaClient: function(algoliasearch, appId, apiKey) {
        return anyCustomClient;

    We forward algoliasearch, which is the original Algolia search client imported inside InstantSearch.js

  • searchParameters[object]

    Additional parameters to pass to the Algolia API (see full documentation).

  • urlSync[boolean|UrlSyncOptions]

    Deprecated in favor of routing.

    URL synchronization configuration. Setting to true will synchronize the needed search parameters with the browser URL.

  • stalledSearchDelay[number]
    Default value: 200

    Time before a search is considered stalled.

  • routing[RoutingOptions]

    Router configuration used to save the UI State into the URL or any client side persistence.

  • searchClient[SearchClient]

    The search client to plug to InstantSearch.js. You should start updating with this syntax to ease the migration to InstantSearch 3.


    // Using the default Algolia client (
    // This is the default client used by InstantSearch. Equivalent to:
    // instantsearch({
    //   appId: 'appId',
    //   apiKey: 'apiKey',
    //   indexName: 'indexName',
    // });
      indexName: 'indexName',
      searchClient: algoliasearch('appId', 'apiKey')
    // Using a custom search client
      indexName: 'indexName',
      searchClient: {
        search(requests) {
          // fetch response based on requests
          return response;
        searchForFacetValues(requests) {
          // fetch response based on requests
          return response;


  • mapping[Object]

    Object used to define replacement query parameter to use in place of another. Keys are current query parameters and value the new value, e.g. { q: 'query' }.

  • threshold[number]
    Default value: 700

    Idle time in ms after which a new state is created in the browser history. The URL is always updated at each keystroke but we only create a “previous search state” (activated when click on back button) every 700ms of idle time.

  • trackedParameters[Array<string>]

    Parameters that will be synchronized in the URL. Default value is ['query', 'attribute:*', 'index', 'page', 'hitsPerPage']. attribute:* means all the faceting attributes will be tracked. You can track only some of them by using [..., 'attribute:color', 'attribute:categories']. All other possible values are all the attributes of the Helper SearchParameters.

  • useHash[boolean]

    If set to true, the URL will be hash based. Otherwise, it’ll use the query parameters using the modern history API.

  • getHistoryState[function]

    Pass this function to override the default history API state we set to null. For example, this could be used to force passing {turbolinks: true} to the history API every time we update it.


  • router[Router]
    Default value: HistoryRouter()

    The router is the part that will save the UI State. By default, it uses an instance of the HistoryRouter with the default parameters.

  • stateMapping[StateMapping]
    Default value: SimpleStateMapping()

    This object transforms the UI state into the object that willl be saved by the router.


  • onUpdatefunction

    Sets an event listener that is triggered when the storage is updated. The function should accept a callback to trigger when the update happens. In the case of the history / URL in a browser, the callback will be called by onPopState.

  • readfunction

    Reads the storage and gets a route object. It does not take parameters, and should return an object.

  • writefunction

    Pushes a route object into a storage. Takes the UI state mapped by the state mapping configured in the mapping.

  • createURLfunction

    Transforms a route object into a URL. It receives an object and should return a string. It may return an empty string.

  • disposefunction

    Cleans up any event listeners.


  • stateToRoutefunction

    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 should return an object of any form as long as this form can be read by the routeToState.

  • routeToStatefunction

    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.


  • searchForFacetValuesfunction

    Performs the requests in the facet values.



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 it is possibly buggy, if you find anything please open an issue.

  • widget

    The widget to add to InstantSearch. Widgets are simple objects that have methods that map the search life cycle in a UI perspective. Usually widgets are created by widget factories like the one provided with InstantSearch.js.


Adds multiple widgets. This can be done before and after the InstantSearch has been started. This feature is considered EXPERIMENTAL and therefore it is possibly buggy, if you find anything please open an issue.

  • widgetsArray<>

    The array of widgets to add to InstantSearch.


Removes a widget. This can be done after the InstantSearch has been started. This feature is considered EXPERIMENTAL and therefore it is possibly buggy, if you find anything please open an issue.

  • widget

    The widget instance to remove from InstantSearch. This widget must implement a dispose() method in order to be gracefully removed.


Removes multiple widgets. This can be done only after the InstantSearch has been started. This feature is considered EXPERIMENTAL and therefore it is possibly buggy, if you find anything please open an issue.

  • widgetsArray<>

    Array of widgets instances to remove from InstantSearch.


Clears the cached answers from Algolia and triggers a new search.


    Ends the initialization of InstantSearch.js and triggers the first search. This method should be called after all widgets have been added to the instance of InstantSearch.js. InstantSearch.js also supports adding and removing widgets after the start as an EXPERIMENTAL feature.


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


        InstantSearch is an EventEmitter and as such it emits events on specific parts of the lifecycle.


        Triggered when the rendering of all the widgets is done. This happens after a search result comes back from Algolia - which means that it is triggered for the first time once everything after all the widgets went through all there lifecycle steps once (getConfiguration, init, render).


        Triggered when an error is reported when calling the API.

        Can't find what you are looking for? Open an issue, we'll get back to you.