> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # instantsearch > Root component of an InstantSearch.js app. export const SearchRequest = () => search request ; export const Index = () => index ; export const Facet = () => facet ; You are viewing the documentation for **InstantSearch.js v4**. To upgrade from v3, see the [migration guide](/doc/guides/building-search-ui/upgrade-guides/js#upgrade-from-v3-to-v4). Looking for the v3 version of this page? [View the v3 docs](https://algolia.com/old-docs/deprecated/instantsearch/js/v3/api-reference/instantsearch). ```ts Signature theme={"system"} 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 ```js Package manager theme={"system"} import instantsearch from 'instantsearch.js'; ``` ```js CDN theme={"system"} window.instantsearch; ``` ## About this widget The `instantsearch` object is the root wrapper component for all widgets. Two parameters are required: * [`indexName`](#param-index-name). The main in which to search. * [`searchClient`](/doc/api-reference/widgets/instantsearch/js#param-search-client). The search client for InstantSearch.js. The [search client](https://github.com/algolia/algoliasearch-client-javascript) needs an `appId` and an `apiKey`, which you can find in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). See also: [Get started with InstantSearch.js](/doc/guides/building-search-ui/getting-started/js) ### Middleware InstantSearch.js provides middleware to help you connect to other systems: * **Insights**. Use the [`insights`](/doc/api-reference/widgets/insights/js) middleware to [send click and conversion events](/doc/guides/building-search-ui/events/js) * **Generic**. With the [`middleware`](/doc/api-reference/widgets/middleware/js) API, you can inject logic into InstantSearch.js. For example, to [send events to Google Analytics](/doc/guides/building-search-ui/going-further/integrate-google-analytics/js). ## Examples ```js JavaScript icon=code theme={"system"} const search = instantsearch({ indexName: "INDEX_NAME", searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"), }); // Add widgets // ... search.start(); ``` ## Options The main index to search into. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... indexName: "INDEX_NAME", }); ``` Provides a search client to `instantsearch`. Read [the custom backend guidance](/doc/guides/building-search-ui/going-further/backend-search/js) on implementing a custom search client. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"), }); ``` The locale used to display numbers. This is passed to [`Number.prototype.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString). ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... numberLocale: "fr", }); ``` Use [`onStateChange`](#param-on-state-change) 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`](#param-on-state-change) or widgets to handle search behavior. A hook is called for every (with [Algolia's search helper](/doc/guides/building-search-ui/upgrade-guides/js#algolia-search-helper) as a parameter). Begin searching by calling [`helper.search()`](https://instantsearchjs.netlify.app/algoliasearch-helper-js/reference.html#AlgoliaSearchHelper#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. ```js JavaScript icon=code theme={"system"} 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(); }, }); ``` Adds a [`uiState`](/doc/api-reference/widgets/ui-state/js) 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. ```js JavaScript icon=code theme={"system"} 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, }, }, }); ``` 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`). ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... onStateChange({ uiState, setUiState }) { // Custom logic setUiState(uiState); }, }); ``` A time period (in ms) after which the search is considered to have stalled. Read the [slow network guide](/doc/guides/building-search-ui/going-further/improve-performance/js) for more information. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... stalledSearchDelay: 500, }); ``` The router configuration used to save the UI state into the URL or any client-side persistence. This object stores the UI state. By default, it uses an instance of the [`history`](/doc/api-reference/widgets/history-router/js) router with its default parameters. 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`. Reads the routing storage and returns a `routeState` object. Writes the `routeState` object into the routing storage. Transforms the `routeState` object into a URL. It receives an object and returns a string (which may be empty). Cleans up all event listeners. Transforms the [`uiState`](/doc/api-reference/widgets/ui-state/js) into the object saved by the router. The default value is provided by [`simple`](/doc/api-reference/widgets/simple-state-mapping/js). 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`. 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](/doc/guides/building-search-ui/going-further/routing-urls/js). You can't use [`initialUiState`](#param-initial-ui-state) with routing as the two options override each other. * Use `initialUiState` for simple and static use cases. * Use `routing` for anything complex or dynamic. ```js boolean theme={"system"} const search = instantsearch({ // ... routing: true, }); ``` ```js object theme={"system"} const search = instantsearch({ // ... routing: { router: instantsearch.routers.history(), stateMapping: instantsearch.stateMappings.simple(), }, }); ``` Enables the Insights middleware and loads the [`search-insights`](https://github.com/algolia/search-insights.js) 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](/doc/guides/building-search-ui/events/js). To use this option with an object, refer to the [Insights middleware options](/doc/api-reference/widgets/insights/js#options). ```js boolean theme={"system"} const search = instantsearch({ // ... insights: true, }); ``` ```js object theme={"system"} const search = instantsearch({ // ... insights: { insightsClient: window.aa, insightsInitParams: { useCookie: false, // … }, // … }, }); ``` Use [`insights`](#param-insights) instead. This function is exposed by the `search-insights` library (usually `window.aa`) and is required for [sending click and conversion events](/doc/guides/building-search-ui/events/js) with the [`insights`](/doc/api-reference/widgets/insights/js) middleware. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... insightsClient: window.aa, }); ``` Test new InstantSearch features without affecting others. 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. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... future: { preserveSharedStateOnUnmount: true, }, }); ``` Whether to display a constant 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. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... future: { persistHierarchicalRootCount: true, }, }); ``` ## Methods Adds widgets to the `instantsearch` instance. You can add widgets to `instantsearch` before and after you start it. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); const searchBox = instantsearch.widgets.searchBox({ // ... }); const hits = instantsearch.widgets.hits({ // ... }); search.addWidgets([searchBox, hits]); ``` Use [`addWidgets([widget])`](#param-add-widgets) instead. Adds a widget to the `instantsearch` instance. You can add widgets to `instantsearch` before and after you start it. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); const searchBox = instantsearch.widgets.searchBox({ // ... }); search.addWidget(searchBox); ``` 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. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.start(); ``` Removes widgets from the `instantsearch` instance. You can only do this after you [start `instantsearch`](#param-start). The widgets you remove from `instantsearch` **must implement a `dispose()` method** to reset the search parameters they manage. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); const searchBox = instantsearch.widgets.searchBox({ // ... }); const hits = instantsearch.widgets.hits({ // ... }); search.removeWidgets([searchBox, hits]); ``` Use [`removeWidgets([widget])`](#param-remove-widgets) instead. Removes a widget from the `instantsearch` instance. You can only do this after you [start `instantsearch`](#param-start). The widget you remove from `instantsearch` **must implement a `dispose()` method** to reset the search parameters they manage. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); const searchBox = instantsearch.widgets.searchBox({ // ... }); search.removeWidget(searchBox); ``` Removes all widgets from the instance. This method doesn't trigger a search. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.dispose(); ``` Injects a [`uiState`](/doc/api-reference/widgets/ui-state/js) 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`](/doc/api-reference/widgets/search-box/js) is necessary to provide a `query`. ```js object theme={"system"} const search = instantsearch({ // ... }); search.start(); search.setUiState({ // Replace INDEX_NAME with your index name INDEX_NAME: { query: 'phone' } }); ``` ```js function theme={"system"} const search = instantsearch({ // ... }); search.start(); search.setUiState(uiState => { return { ...uiState, // Replace INDEX_NAME with your index name INDEX_NAME: { ...uiState.INDEX_NAME, query: 'phone' } } }); ``` Clears the Algolia responses cache and triggers a new search. For more information, read the [InstantSearch caching guide](/doc/guides/building-search-ui/going-further/improve-performance/js#caching). ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.refresh(); ``` ## Properties 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`](#param-stalled-search-delay) expires. * `error`. The search failed. The error is available in the `error` property. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.start(); search.on("render", () => { console.log(search.status); }); ``` The error that occurred during the search. This is only defined when `status` is `'error'`. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.start(); // Error handler prevents uncaught errors search.on("error", () => {}); search.on("render", () => { console.log(search.status === "error" && search.error); }); ``` 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`](/doc/api-reference/widgets/render-state/js) page. ```js JavaScript icon=code theme={"system"} const indexName = ""; const search = instantsearch({ indexName, // ... }); search.addWidgets([ searchBox({ container: "", }), ]); search.start(); console.log(search.renderState[indexName].searchBox); /* { query: string; refine: Function; clear: Function; isSearchStalled: boolean; widgetParams: object; } */ ``` ## Events Triggered when all widgets are rendered. This happens after every search request. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.on("render", () => { // Do something on render }); ``` Triggered when calling the API reports an error. ```js JavaScript icon=code theme={"system"} const search = instantsearch({ // ... }); search.on("error", ({ error }) => { // Do something on error }); ```