> ## 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
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
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
});
```