<CurrentRefinements>
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.
<CurrentRefinements // Optional props includedAttributes={string[]} excludedAttributes={string[]} transformItems={function} classNames={object} ...props={ComponentProps<'div'>} />
1
import { CurrentRefinements } from 'react-instantsearch';
About this widget
<CurrentRefinements>
is a widget that lets you display the list of active refinements in the search.
You can also create your own UI with
useCurrentRefinements()
.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
import React from 'react';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, CurrentRefinements } from 'react-instantsearch';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function App() {
return (
<InstantSearch indexName="instant_search" searchClient={searchClient}>
<CurrentRefinements />
</InstantSearch>
);
}
Props
includedAttributes
|
type: string[]
default: []
The attributes to include (all by default). This parameter can’t be used with In the example below, only the |
||
Copy
|
|||
excludedAttributes
|
type: string[]
default: ['query']
The attributes to exclude from the widget. This parameter can’t be used with In the example below, the |
||
Copy
|
|||
transformItems
|
type: (items: object[], metadata: { results: SearchResults }) => object[]
default: items => items
Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items. In addition, the full |
||
Copy
|
|||
classNames
|
type: Partial<CurrentRefinementsClassNames>
Optional
The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.
|
||
Copy
|
|||
...props
|
type: React.ComponentProps<'div'>
Optional
Any |
||
Copy
|
Hook
React InstantSearch let you create your own UI for the <CurrentRefinements>
widget with useCurrentRefinements()
. Hooks provide APIs to access the widget state and interact with InstantSearch.
The useCurrentRefinements()
Hook accepts parameters and returns APIs.
Usage
First, create your React component:
import { useCurrentRefinements } from 'react-instantsearch';
function CustomCurrentRefinements(props) {
const { items, canRefine, refine } = useCurrentRefinements(props);
return <>{/* Your JSX */}</>;
}
Then, render the widget:
<CustomCurrentRefinements {...props} />
Parameters
Hooks accept parameters. You can pass them manually, or forward the props from your custom component.
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.
includedAttributes
|
type: string[]
default: []
The attributes to include (all by default). This parameter can’t be used with In the example below, only the |
||
Copy
|
|||
excludedAttributes
|
type: string[]
default: ['query']
The attributes to exclude from the widget. This parameter can’t be used with In the example below, the |
||
Copy
|
|||
transformItems
|
type: (items: object[], metadata: { results: SearchResults }) => object[]
default: items => items
Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items. In addition, the full |
||
Copy
|
APIs
Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.
items
|
type: CurrentRefinementsItem[]
All the currently refined items grouped by attribute.
Copy
|
||
canRefine
|
type: boolean
Whether the search state can be refined. |
||
refine
|
type: (value: CurrentRefinementsItem) => void
Clears a single refinement and triggers a new search. |
Example
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
import React from 'react';
import { useCurrentRefinements } from 'react-instantsearch';
function CustomCurrentRefinements(props) {
const { items, refine } = useCurrentRefinements(props);
return (
<ul>
{items.map((item) => (
<li key={[item.indexName, item.label].join('/')}>
<span>{item.label}:</span>
{item.refinements.map((refinement) => (
<span key={refinement.label}>
<span>{refinement.label}</span>
<button
type="button"
onClick={(event) => {
if (isModifierClick(event)) {
return;
}
refine(refinement);
}}
>
Remove
</button>
</span>
))}
</li>
))}
</ul>
);
}
function isModifierClick(event) {
const isMiddleClick = event.button === 1;
return Boolean(
isMiddleClick ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey
);
}