<RefinementList>
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.
<RefinementList attribute={string} // Optional parameters operator={'and' | 'or'} limit={number} showMore={boolean} showMoreLimit={number} searchable={boolean} searchablePlaceholder={string} sortBy={string[] | function} escapeFacetValues={boolean} transformItems={function} classNames={object} translations= {object} ...props={ComponentProps<'div'>} />
1
import { RefinementList } from 'react-instantsearch';
About this widget
<RefinementList>
is a widget that lets users filter the dataset using multi-select facets.
A refinement list only displays the most relevant facet values for the current search context. The sortBy
option only affects how the facets are ordered, not which facets are returned.
The widget also implements search for facet values, which provides a mini search inside the facet values. This helps users find uncommon facet values.
The attribute
provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting
parameter with the API.
If you are using the searchable
prop, you also need to make the attribute searchable using the dashboard or using the searchable
modifier of attributesForFaceting
with the API.
Disappearing facet values
With many facet values, the available options can change depending on the user’s query. The refinement widget displays the most common facet values for a given query.
A user’s chosen value can vanish if they alter the query. This occurs because only the most common facet values are displayed when there are many options. A previously selected value might not appear if it’s uncommon for the new query.
To also show less common values, adjust the maximum number of values with the configure
widget.
It doesn’t change how many items are shown: the limits you set with limit
and showMoreLimit
still apply.
How to implement a “Show more” feature
A custom useRefinementList()
widget displays up to showMoreLimit
refinement items
.
You can sort the items as desired before they’re trimmed.
However, you’ll need to slice to the appropriate limit
and keep track of isShowingMore
in the local state:
1
2
3
4
5
6
7
8
9
10
11
12
13
const CustomRefinementList = connectRefinementList(function RefinementList({
items,
limit,
showMoreLimit
}) {
const [isShowingMore, toggleShowMore] = React.useState(false)
const itemsToDisplay = items.slice(
0,
isShowingMore ? showMoreLimit : limit
)
// render using `itemsToDisplay`
})
You can also create your own UI with
useRefinementList()
.
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, RefinementList } from 'react-instantsearch';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function App() {
return (
<InstantSearch indexName="instant_search" searchClient={searchClient}>
<RefinementList attribute="brand" />
</InstantSearch>
);
}
Props
attribute
|
type: string
Required
The name of the attribute in the records. To avoid unexpected behavior, you can’t use the same |
||
Copy
|
|||
operator
|
type: 'and'|'or'
default: 'or'
Optional
How the facets are combined.
|
||
Copy
|
|||
limit
|
type: number
default: 10
Optional
How many facet values to retrieve. When you set |
||
Copy
|
|||
showMore
|
type: boolean
default: false
Optional
Whether to display a button that expands the number of items. |
||
Copy
|
|||
showMoreLimit
|
type: number
Optional
The maximum number of items to display if the widget is showing more items. |
||
Copy
|
|||
searchable
|
type: boolean
default: false
Optional
Whether to add a search input to let users search for more facet values. You need to make the In some situations, refined facet values might not be present in the data returned by Algolia. |
||
Copy
|
|||
searchablePlaceholder
|
type: string
Optional
The value of the search input’s placeholder. |
||
Copy
|
|||
sortBy
|
type: string[] | (a: FacetValue, b: FacetValue) => number
default: ["isRefined", "count:desc", "name:asc"], or `facetOrdering` if set
Optional
How to sort refinements. Must be one or more of the following strings:
You can also use a sort function that behaves like the standard Javascript When you don’t set this parameter, and you’ve set In some situations, refined facet values might not be present in the data returned by Algolia. |
||
Copy
|
|||
escapeFacetValues
|
type: boolean
default: true
Optional
Escapes the content of the facet values returned by Algolia. When using this parameter, the highlighting tags are always |
||
Copy
|
|||
transformItems
|
type: (items: object[], metadata: { results: SearchResults }) => object[]
Optional
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<RefinementListClassNames>
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
|
|||
translations
|
type: Partial<RefinementListTranslations>
Optional
A dictionary of translations to customize the UI text and support internationalization.
|
||
Copy
|
|||
...props
|
type: React.ComponentProps<'div'>
Optional
Any |
||
Copy
|
Hook
React InstantSearch let you create your own UI for the <RefinementList>
widget with useRefinementList()
. Hooks provide APIs to access the widget state and interact with InstantSearch.
The useRefinementList()
Hook accepts parameters and returns APIs.
Usage
First, create your React component:
import { useRefinementList } from 'react-instantsearch';
function CustomRefinementList(props) {
const {
items,
hasExhaustiveItems,
createURL,
refine,
sendEvent,
searchForItems,
isFromSearch,
canRefine,
canToggleShowMore,
isShowingMore,
toggleShowMore,
} = useRefinementList(props);
return <>{/* Your JSX */}</>;
}
Then, render the widget:
<CustomRefinementList {...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.
attribute
|
type: string
Required
The name of the attribute in the records. To avoid unexpected behavior, you can’t use the same |
||
Copy
|
|||
operator
|
type: "and"|"or"
default: "or"
Optional
How the filters are combined together.
|
||
Copy
|
|||
limit
|
type: number
default: 10
Optional
How many facet values to retrieve. When you set |
||
Copy
|
|||
showMore
|
type: boolean
default: false
Optional
Whether to display a button that expands the number of items. |
||
Copy
|
|||
showMoreLimit
|
type: number
Optional
The maximum number of items to display if the widget is showing more items. |
||
Copy
|
|||
sortBy
|
type: string[] | (a: FacetValue, b: FacetValue) => number
default: ["isRefined", "count:desc", "name:asc"], or `facetOrdering` if set
Optional
How to sort refinements. Must be one or more of the following strings:
You can also use a sort function that behaves like the standard Javascript When you don’t set this parameter, and you’ve set In some situations, refined facet values might not be present in the data returned by Algolia. |
||
Copy
|
|||
escapeFacetValues
|
type: boolean
default: true
Optional
Escapes the content of the facet values returned by Algolia. When using this parameter, the highlighting tags are always |
||
Copy
|
|||
transformItems
|
type: (items: object[], metadata: { results: SearchResults }) => object[]
Optional
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: RefinementListItem[]
The list of filtering values returned by Algolia.
Copy
|
||
hasExhaustiveItems
|
type: boolean
Whether the results are exhaustive. |
||
createURL
|
type: (value: string) => string
Creates the next state URL of a selected refinement. |
||
refine
|
type: (value: string) => string
Applies the selected refinement. |
||
sendEvent
|
type: (eventType: string, facetValue: string, eventName?: string) => void
Sends an event to the Insights middleware. |
||
searchForItems
|
type: (query: string) => void
Searches for values in the list. |
||
isFromSearch
|
type: boolean
Whether the values are from an index search. |
||
canRefine
|
type: boolean
Whether a refinement can be applied. |
||
canToggleShowMore
|
type: boolean
Whether the Show more button can be activated, meaning there are enough additional items to display, or already displaying over the |
||
isShowingMore
|
type: boolean
Whether the menu is displaying all the menu items. |
||
toggleShowMore
|
type: () => void
Toggles the number of values displayed between |
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 { useRefinementList } from 'react-instantsearch';
function CustomRefinementList(props) {
const {
items,
refine,
searchForItems,
canToggleShowMore,
isShowingMore,
toggleShowMore,
} = useRefinementList(props);
return (
<>
<input
type="search"
autoComplete="off"
autoCorrect="off"
autoCapitalize="off"
spellCheck={false}
maxLength={512}
onChange={(event) => searchForItems(event.currentTarget.value)}
/>
<ul>
{items.map((item) => (
<li key={item.label}>
<label>
<input
type="checkbox"
checked={item.isRefined}
onChange={() => refine(item.value)}
/>
<span>{item.label}</span>
<span>({item.count})</span>
</label>
</li>
))}
</ul>
<button onClick={toggleShowMore} disabled={!canToggleShowMore}>
{isShowingMore ? 'Show less' : 'Show more'}
</button>
</>
);
}