What is React InstantSearch?
This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.
If you were using React InstantSearch v6, you can upgrade to v7.
If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.
If you want to keep using React InstantSearch v6, you can find the archived documentation.
On this page
React InstantSearch is an open source UI library for React that lets you build a search interface in your frontend app.
InstantSearch focuses on enhancing your frontend with primitives that you can combine to create unique search interfaces.
InstantSearch supports server-side rendering and offers full routing capabilities.
InstantSearch suite includes various “flavors” to meet different development needs:
A progressive customization API
InstantSearch provides three layers of usage with each layer giving you more control:
- Start with a predefined UI widget which you can configure and style with CSS.
- To change the render output of a widget, use Hooks to render what you want.
- To implement something that doesn’t exist, create a custom Hook.
Using widgets
The recommended way to use React InstantSearch is to use predefined widgets such as <SearchBox>
or <RefinementList>
.
Widgets provide features and a rendered output. You can place them anywhere on your UI, configure them, and style them with CSS.
1
2
3
4
5
6
7
8
9
10
11
12
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, RefinementList } from 'react-instantsearch';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function App() {
return (
<InstantSearch searchClient={searchClient} indexName="instant_search">
<RefinementList attribute="brand" />
</InstantSearch>
);
}
The <InstantSearch>
provider connects your InstantSearch app to your Algolia application.
It accepts a search client and an index.
Then, the <RefinementList>
widget lists the brands, allowing your users to “refine” their search by brand.
Using Hooks
You may want to control the render output of a widget. For example, when using React InstantSearch with a component library like Material UI or when rendering to a non-DOM target like React Native.
To do so, use Hooks:
useBreadcrumb()
useClearRefinements()
useConfigure()
useCurrentRefinements()
useDynamicWidgets()
useHierarchicalMenu()
useHits()
useHitsPerPage()
useInfiniteHits()
useMenu()
usePagination()
usePoweredBy()
useRange()
useRefinementList()
useSearchBox()
useSortBy()
useStats()
useToggleRefinement()
Hooks return the necessary APIs for you to build the UI as you see fit.
Example component
Here’s an example of a custom <RefinementList>
component created with useRefinementList()
, and mounted in the <InstantSearch>
provider.
1
2
3
4
5
6
7
8
9
10
11
12
13
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch';
import { RefinementList } from './RefinementList';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function App() {
return (
<InstantSearch searchClient={searchClient} indexName="instant_search">
<RefinementList attribute="brand" />
</InstantSearch>
);
}
Pass stable references
When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback()
). Objects and arrays are memoized; you don’t need to stabilize them.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import React, { useCallback } from 'react';
import { InstantSearch, useHits } from 'react-instantsearch';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function Search({ cartItems }) {
const transformItems = useCallback(
(items) =>
items.map((item) => ({
...item,
isInCart: Boolean(
cartItems.find((cartItem) => cartItem.objectID === item.objectID)
),
})),
[cartItems]
);
const { hits } = useHits({ transformItems });
return <>{/* Your JSX */}</>;
}
function App({ cartItems }) {
return (
<InstantSearch searchClient={searchClient} indexName="instant_search">
<Search cartItems={cartItems} />
</InstantSearch>
);
}
Creating your own Hooks
React InstantSearch works with all InstantSearch.js connectors: from Algolia, from the community, or even with your own.
To create your own Hook, you first need to create your connector.
Then, you can use useConnector()
to turn your connector into a Hook:
1
2
3
4
5
6
import { useConnector } from 'react-instantsearch';
import { connectMyWidget } from './connectMyWidget';
export function useMyWidget(props) {
return useConnector(connectMyWidget, props);
}
You can now use your new Hook and component anywhere within <InstantSearch>
.
CSS theme
The UI widgets from React InstantSearch are compatible with the default CSS theme.
If you use Hooks and you want to use the default theme in your app, you can follow the markup from the provided UI widgets and use the InstantSearch class names.
Here’s a preview of the theme:
For more information, see Style your widgets.
Need help?
React InstantSearch is worked on full-time by Algolia’s JavaScript team.
Join the community
Ask questions and find answers on those following platforms.
- Algolia Community Discord
- Stack Overflow
- Open and read GitHub issues
Provide feedback
- Write a feature request
- Use the Did you find this page helpful? form below
Stay up to date
- Look at the changelog.
Contributing?
All contributors are welcome, from casual to regular. Feel free to open a pull request.