instantsearch
instantsearch({ indexName: string, searchClient: object, // Optional parameters numberLocale: string, searchFunction: function, initialUiState: object, onStateChange: function, stalledSearchDelay: number, routing: boolean|object, insights: boolean|object, insightsClient: function, future: { preserveSharedStateOnUnmount: boolean, persistHierarchicalRootCount: boolean, }, });
1
import instantsearch from 'instantsearch.js';
About this widget
You are currently reading the documentation for InstantSearch.js v4. Read our migration guide to learn how to upgrade from v3 to v4. You can still access the V3 documentation for this page.
The instantsearch
object is the root wrapper component for all widgets.
Two parameters are required:
indexName
: your search UI’s main indexsearchClient
: the search client for InstantSearch.js. The search client needs anappId
and anapiKey
: find those credentials in your Algolia dashboard.
The getting started guide will help you get up and running 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 functionality into InstantSearch.js. For example, to send events to Google Analytics.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
const search = instantsearch({
indexName: 'INDEX_NAME',
searchClient: algoliasearch(
'YourApplicationID',
'YourSearchOnlyAPIKey'
),
});
// Add widgets
// ...
search.start();
Options
indexName
|
type: string
Required
The main index to search into. |
||
Copy
|
|||
searchClient
|
type: object
Required
Provides a search client to |
||
Copy
|
|||
numberLocale
|
type: string
Optional
The locale used to display numbers. This is passed to |
||
Copy
|
|||
searchFunction
|
Deprecated
type: function
Optional
Use This option allows you to take control of search behavior. For example, to avoid doing searches at page load. When this option is set, A hook is called each time a search is requested (with Algolia’s search helper as a parameter).
Begin searching by calling When modifying the state of the helper within |
||
Copy
|
|||
initialUiState
|
type: object
Optional
Adds a Replace |
||
Copy
|
|||
onStateChange
|
type: function
Optional
Triggered when the state changes. This can be helpful for performing custom logic on a state change. When using |
||
Copy
|
|||
stalledSearchDelay
|
type: number
default: 200
Optional
A time period (in ms) after which the search is considered to have stalled. Read the slow network guide for more information. |
||
Copy
|
|||
routing
|
type: boolean|object
default: false
Optional
The router configuration used to save the UI state into the URL or any client-side persistence.
It’s either a
For more information, see Sync your URLs. You can’t use
|
||
Copy
|
|||
insights
|
since: v4.55.0
type: boolean|object
default: false
Optional
Enables the Insights middleware and loads the To use this option with an object, refer to the Insights middleware options. |
||
Copy
|
|||
insightsClient
|
Deprecated
type: function
Optional
Use This function is exposed by the |
||
Copy
|
|||
future
|
type: object
Optional
Test these new InstantSearch features without affecting others:
|
||
preserveSharedStateOnUnmount
|
since: v4.58.0
type: boolean
default: false
Optional
Changes the way If If |
||
Copy
|
|||
persistHierarchicalRootCount
|
since: v4.62.0
type: boolean
default: false
Optional
Whether to display a constant facet value count at the root of a hierarchical menu with active refinements. If If |
||
Copy
|
Methods
addWidgets
|
Adds widgets to the You can add widgets to |
||
Copy
|
|||
addWidget
|
Deprecated
Use Adds a widget to the You can add widgets to |
||
Copy
|
|||
start
|
Finalizes the setup of Call this method after you have added all your required widgets to |
||
Copy
|
|||
removeWidgets
|
Removes widgets from the The widgets you remove from |
||
Copy
|
|||
removeWidget
|
Deprecated
Use Removes a widget from the The widget you remove from |
||
Copy
|
|||
dispose
|
Removes all widgets from the instance. This method doesn’t trigger a search. |
||
Copy
|
|||
setUiState
|
Injects a For this option to work, the widgets responsible for each UI state attribute must be mounted.
For example, a |
||
Copy
|
|||
refresh
|
Clears the Algolia responses cache and triggers a new search. For more information, read the InstantSearch caching guide. |
||
Copy
|
Properties
status
|
type: "idle" | "loading" | "stalled" | "error"
The status of the in-progress search. Possible values are:
|
||
Copy
|
|||
error
|
type: Error | undefined
The error that occurred during the search. This is only defined when |
||
Copy
|
|||
renderState
|
type: RenderState | undefined
The |
||
Copy
|
Events
render
|
Triggered when all widgets are rendered. This happens after every search request. |
||
Copy
|
|||
error
|
Triggered when calling the API reports an error. |
||
Copy
|