instantsearch

Description

InstantSearch is the main component of InstantSearch.js. This object 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 will 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.

If you want to get up and running quickly with InstantSearch.js, have a look at the getting started.

Usage

const search = instantsearch({ 
  indexName: string, 
  searchClient: SearchClient, 
  numberLocale: [string], 
  searchFunction: [function], 
  searchParameters: [object], 
  stalledSearchDelay: [number], 
  routing: [RoutingOptions], 
}: InstantSearchOptions);

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

Options

InstantSearchOptions

• indexNamestring

  The name of the main index

• searchClientSearchClient

  The search client to plug to InstantSearch.js

  Usage:

  // Using the default Algolia search client
  instantsearch({
    indexName: 'indexName',
    searchClient: algoliasearch('appId', 'apiKey')
  });
  
  // Using a custom search client
  instantsearch({
    indexName: 'indexName',
    searchClient: {
      search(requests) {
        // fetch response based on requests
        return response;
      },
      searchForFacetValues(requests) {
        // fetch response based on requests
        return response;
      }
    }
  });
  

• 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 helper.search(). This option allows you to avoid doing searches at page load for example.

• searchParameters[object]

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

• 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

• searchfunction

  Performs the requests in the hits.

• searchForFacetValuesfunction

  Performs the requests in the facet values.

RoutingOptions

• 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.

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.

StateMapping

• 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.

Methods

addWidget(widget)

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.

addWidgets(widgets)

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.

removeWidget(widget)

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.

removeWidgets(widgets)

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.

refresh()

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

start()

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.

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.

Events

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

render

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).

error

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.