instantsearch

Root component of an InstantSearch.js app.

You are viewing the documentation for InstantSearch.js v4. To upgrade from v3, see the migration guide. Looking for the v3 version of this page? View the v3 docs.

Signature

instantsearch({
  indexName: string,
  searchClient: object,
  numberLocale?: string,
  searchFunction?: function,
  initialUiState?: object,
  onStateChange?: function,
  stalledSearchDelay?: number,
  routing?: boolean | object,
  insights?: boolean | object,
  insightsClient?: function,
  future?: {
    preserveSharedStateOnUnmount: boolean,
    persistHierarchicalRootCount: boolean,
  },
});

Import

Package manager

import instantsearch from 'instantsearch.js';

About this widget

The instantsearch object is the root wrapper component for all widgets.

Two parameters are required:

• indexName. Your main search index
• searchClient. The search client for InstantSearch.js. The search client needs an appId and an apiKey, which you can find in the Algolia dashboard.

See also: Get started with InstantSearch.js

Middleware

InstantSearch.js provides middleware to help you connect to other systems:

• Insights. Use the insights middleware to send click and conversion events
• Generic. With the middleware API, you can inject logic into InstantSearch.js. For example, to send events to Google Analytics.

Examples

JavaScript

const search = instantsearch({
  indexName: "INDEX_NAME",
  searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
});

// Add widgets
// ...

search.start();

Options

indexName · string · required

The main index to search into.

JavaScript

const search = instantsearch({
  // ...
  indexName: "INDEX_NAME",
});

searchClient · object · required

Provides a search client to instantsearch. Read the custom backend guidance on implementing a custom search client.

JavaScript

const search = instantsearch({
  // ...
  searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
});

numberLocale · string

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

JavaScript

const search = instantsearch({
  // ...
  numberLocale: "fr",
});

searchFunction · function · deprecated

Use onStateChange instead.

This option lets you take control of search behavior. For example, to avoid doing searches at page load.

When this option is set, search.helper won’t emit events. Instead, use onStateChange or widgets to handle search behavior.

A hook is called each time a search is requested (with Algolia’s search helper as a parameter). Begin searching by calling helper.search().

When modifying the state of the helper within search-function, the helper resets the page to 0. To keep the current page, store the page information, modify the state, and reapply pagination.

JavaScript

const search = instantsearch({
  // ...
  searchFunction(helper) {
    if (helper.state.query) {
      helper.search();
    }
  },
});

// Example which avoids the page resetting 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();
  },
});

initialUiState · object

Adds a uiState to your instantsearch instance, which provides an initial state to your widgets.

Since this sets the initial state for your UI, you need to include the corresponding widgets in your app. For example, page: 5 as initial state only has an effect if you include the pagination widget as well.

Replace YourIndexName with the name of your Algolia index.

JavaScript

const search = instantsearch({
  // ...
  initialUiState: {
    YourIndexName: {
      // Sets the initial search query for the searchBox widget
      query: "phone",
      // Sets the initial page number for the pagination widget
      page: 5,
    },
  },
});

onStateChange · function

Triggered when the state changes. This can be helpful for performing custom logic on a state change.

When using onStateChange, the instance is under your control. You’re responsible for updating the UI state (with setUiState).

JavaScript

const search = instantsearch({
  // ...
  onStateChange({ uiState, setUiState }) {
    // Custom logic

    setUiState(uiState);
  },
});

stalledSearchDelay · number · default: 200

A time period (in ms) after which the search is considered to have stalled. Read the slow network guide for more information.

JavaScript

const search = instantsearch({
  // ...
  stalledSearchDelay: 500,
});

routing · boolean | object · default: false

The router configuration used to save the UI state into the URL or any client-side persistence.

Show routing attributes

routing.router · object

This object stores the UI state. By default, it uses an instance of the history router with its default parameters.

Show router attributes

router.onUpdate · function

Adds an event listener that makes InstantSearch aware of external changes to the storage medium (such as the URL). Typically you’ll set up a listener for popstate, which triggers a callback with the current routeState.

router.read · function

Reads the routing storage and returns a routeState object.

router.write · function

Writes the routeState object into the routing storage.

router.createURL · function

Transforms the routeState object into a URL. It receives an object and returns a string (which may be empty).

router.dispose · function

Cleans up all event listeners.

routing.stateMapping · object

Transforms the uiState into the object saved by the router. The default value is provided by simple.

Show stateMapping attributes

stateMapping.stateToRoute · function

Transforms a ui-state representation into a routeState object. It receives an object that contains the UI state of all the widgets on the page. It can return any object that is readable by routeToState.

stateMapping.routeToState · function

Transforms routeState into a ui-state representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.

For more information, see Sync your URLs.

You can’t use initialUiState with routing as the two options override each other.

• Use initialUiState for simple and static use cases.
• Use routing for anything complex or dynamic.

boolean

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

insights · boolean | object · default: false · since: v4.55.0

Enables the Insights middleware and loads the search-insights library (if not already loaded). The Insights middleware sends view and click events automatically, and lets you set up your own click and conversion events.

To use this option with an object, refer to the Insights middleware options.

boolean

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

insightsClient · function · deprecated

Use insights instead.

This function is exposed by the search-insights library (usually window.aa) and is required for sending click and conversion events with the insights middleware.

JavaScript

const search = instantsearch({
  // ...
  insightsClient: window.aa,
});

future · object

Test new InstantSearch features without affecting others.

Show future attributes

future.preserveSharedStateOnUnmount · boolean · default: false · since: v4.58.0

Changes the way dispose is used in the InstantSearch lifecycle.

If false (the default), each widget unmounting will also remove its state, even if multiple widgets read that UI state.

If true, each widget unmounting will only remove its state if it’s the last of its type. This allows you to dynamically add and remove widgets without losing their state.

JavaScript

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

future.persistHierarchicalRootCount · boolean · default: false · since: v4.62.0

Whether to display a constant facet value count at the root of a hierarchical menu with active refinements.

If false (default), the facet value count at the root level shows the facet value count of the refined (child) facet’s parent.

If true, the facet value count at the root level shows the sum of the facet value counts of all its children, with or without refined children.

JavaScript

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

Methods

addWidgets · function

Adds widgets to the instantsearch instance.

You can add widgets to instantsearch before and after you start it.

JavaScript

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

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

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

search.addWidgets([searchBox, hits]);

addWidget · deprecated

Use addWidgets([widget]) instead.

Adds a widget to the instantsearch instance.

You can add widgets to instantsearch before and after you start it.

JavaScript

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

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

search.addWidget(searchBox);

start · function

Finalizes the setup of instantsearch and triggers the first search.

Call this method after you have added all your required widgets to instantsearch. You can also add widgets after instantsearch has started, but these widgets aren’t considered during searches made before you add them.

JavaScript

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

search.start();

removeWidgets

Removes widgets from the instantsearch instance. You can only do this after you start instantsearch.

The widgets you remove from instantsearch must implement a dispose() method to reset the search parameters they manage.

JavaScript

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

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

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

search.removeWidgets([searchBox, hits]);

removeWidget · deprecated

Use removeWidgets([widget]) instead.

Removes a widget from the instantsearch instance. You can only do this after you start instantsearch.

The widget you remove from instantsearch must implement a dispose() method to reset the search parameters they manage.

JavaScript

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

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

search.removeWidget(searchBox);

dispose

Removes all widgets from the instance. This method doesn’t trigger a search.

JavaScript

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

search.dispose();

setUiState

Injects a uiState into the instance without relying on internal events (such as connectors’ refine or widget interactions).

For this option to work, the widgets responsible for each UI state attribute must be mounted. For example, a searchBox is necessary to provide a query.

object

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

search.start();

search.setUiState({
  // Replace INDEX_NAME with your index name
  INDEX_NAME: {
    query: 'phone'
  }
});

refresh

Clears the Algolia responses cache and triggers a new search. For more information, read the InstantSearch caching guide.

JavaScript

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

search.refresh();

Properties

status · string

The status of the in-progress search.

Possible values are:

• idle. No search is in progress.
• loading. The search is loading. Use loading for immediate feedback on an action. For loading indicators, use 'stalled' instead.
• stalled. The search is stalled. This is triggered after stalledSearchDelay expires.
• error. The search failed. The error is available in the error property.

JavaScript

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

search.start();

search.on("render", () => {
  console.log(search.status);
});

error · Error | undefined

The error that occurred during the search. This is only defined when status is 'error'.

JavaScript

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

search.start();

// Error handler prevents uncaught errors
search.on("error", () => {});

search.on("render", () => {
  console.log(search.status === "error" && search.error);
});

renderState · RenderState | undefined

The renderState provides access to all the data to render the widgets, including the methods to refine the search. More information can be found in the renderState page.

JavaScript

const indexName = "<index-name>";
const search = instantsearch({
  indexName,
  // ...
});
search.addWidgets([
  searchBox({
    container: "<your-container>",
  }),
]);
search.start();

console.log(search.renderState[indexName].searchBox);
/*
  {
    query: string;
    refine: Function;
    clear: Function;
    isSearchStalled: boolean;
    widgetParams: object;
  }
*/

Events

render

Triggered when all widgets are rendered. This happens after every search request.

JavaScript

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

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

error

Triggered when calling the API reports an error.

JavaScript

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

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