instantsearch

Edit this page

Description

InstantSearch is the main component of InstantSearch.js. This object manages the widget and let 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.

Usage

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

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

Options

InstantSearchOptions

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

  • createAlgoliaClient[function]

    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. Usage:

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

    We forward algoliasearch which is the original algoliasearch module imported inside instantsearch.js

  • searchParameters[object]

    Additional parameters to pass to the Algolia API. Full documentation

  • urlSync[boolean|UrlSyncOptions]

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

UrlSyncOptions

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

    Idle time in ms after which a new state is created in the browser history. The default value is 700. 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.

    There’s a special is_v parameter that will get added everytime, it tracks the version of instantsearch.js linked to the url.

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

Methods

addWidget(widget)

Add a widget

  • widgetWidget

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

start()

The start methods 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

    Events

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

    render

    The `render` event is 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 once everything after all the widgets went through all there lifecycle steps once (getConfiguration, init, render).