> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# RefinementList
> Shows a list of facets for refining search results.
export const Records = () =>
records
;
export const Index = () =>
index
;
This is the **React InstantSearch v7** documentation.
If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
If you were using React InstantSearch Hooks,
this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
```tsx Signature theme={"system"}
}
/>
```
## Import
```jsx JavaScript icon=code theme={"system"}
import { RefinementList } from "react-instantsearch";
```
Preview this widget and its behavior.
## About this widget
`` 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`](#param-sort-by) option only affects how the facets are ordered, not which facets are returned.
This widget includes a "search for facet values" feature,
enabling users to search through the [values of a specific facet attribute](/doc/guides/managing-results/refine-results/faceting#search-for-facet-values).
This helps you find uncommon facet values.
The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.
If you are using the [`searchable`](#param-searchable) prop, you also need to make the attribute searchable using the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the `searchable` modifier of [`attributesForFaceting`](/doc/api-reference/api-parameters/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`](/doc/api-reference/widgets/configure/react) widget.
It doesn't change how many items are shown: the limits you set with [`limit`](/doc/api-reference/widgets/refinement-list/react#param-limit) and [`showMoreLimit`](/doc/api-reference/widgets/refinement-list/react#param-show-more-limit) 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:
```jsx JavaScript icon=code theme={"system"}
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`](#hook).
## Examples
```jsx JavaScript icon=code theme={"system"}
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 (
);
}
```
## Props
The name of the attribute in the .
To avoid unexpected behavior, you can't use the same `attribute` prop in a different type of widget.
```jsx JavaScript icon=code theme={"system"}
;
```
How the facets are combined.
* `'or'`: Returns results matching any of the selected values.
* `'and'`: Returns results matching all selected values.
Use [filters or facet filters](/doc/guides/managing-results/refine-results/filtering/in-depth/filters-and-facetfilters) for more complex result refinement.
```jsx JavaScript icon=code theme={"system"}
;
```
How many facet values to retrieve.
When you set [`showMore`](#param-show-more) and [`showMoreLimit`](#param-show-more-limit),
this is the number of facet values to display before clicking the Show more button.
```jsx JavaScript icon=code theme={"system"}
;
```
Whether to display a button that expands the number of items.
```jsx JavaScript icon=code theme={"system"}
;
```
The maximum number of items to display if the widget is showing more items.
```jsx JavaScript icon=code theme={"system"}
;
```
Whether to add a search input to let users search for more facet values.
You need to make the `attribute` searchable using the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard)) or using the `searchable` modifier of [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) with the API.
In some situations, refined facet values might not be present in the data
returned by Algolia.
```jsx JavaScript icon=code theme={"system"}
;
```
The value of the search input's placeholder.
```jsx JavaScript icon=code theme={"system"}
;
```
How to sort refinements. Must be one or more of the following strings:
* `"count"` (same as `"count:desc"`)
* `"count:asc"`
* `"count:desc"`
* `"name"` (same as `"name:asc"`)
* `"name:asc"`
* `"name:desc"`
* `"isRefined"` (same as `"isRefined:asc"`)
* `"isRefined:asc"`
* `"isRefined:desc"`
You can also use a sort function that behaves like the standard JavaScript [`compareFunction`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
When you don't set this parameter,
and you've set `facetOrdering` for this facet in `renderingContent`,
facets are sorted using `facetOrdering` and use the default order as a fallback.
In some situations, refined facet values might not be present in the data
returned by Algolia.
```jsx String theme={"system"}
;
```
```jsx Function theme={"system"}
const sortByName = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function Search() {
return (
);
}
```
```tsx Function (TypeScript) theme={"system"}
import type { RefinementListProps } from "react-instantsearch";
const sortByName: RefinementListProps["sortBy"] = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function Search() {
return (
);
}
```
Escapes the content of the facet values returned by Algolia.
When using this parameter,
the highlighting tags are always [`mark`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark).
```jsx JavaScript icon=code theme={"system"}
;
```
A function that receives the list of items before they are displayed.
It should return a new array with the same structure.
Use this to transform, filter, or reorder the items.
The function also has access to the full `results` data,
including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```jsx JavaScript theme={"system"}
const transformItems = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Search() {
return (
);
}
```
```tsx TypeScript theme={"system"}
import type { RefinementListProps } from 'react-instantsearch';
const transformItems: RefinementListProps['transformItems'] = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Search() {
return (
);
}
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets)
and pass to the widget's elements.
It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com)
or [Tailwind CSS](https://tailwindcss.com).
* `root`. The root element of the widget.
* `noRefinementRoot`. The root element when there are no refinements.
* `searchBox`. The search box element.
* `noResults`. The root element of the widget when there are no results.
* `list`. The list element.
* `item`. Each item element.
* `selectedItem`. Each selected item element.
* `label`. The label of each item.
* `checkbox`. The checkbox of each item.
* `labelText`. The text element of each label.
* `count`. The count of each item.
* `showMore`. The "Show more" button.
* `disabledShowMore`. The disabled "Show more" button.
```jsx JavaScript icon=code theme={"system"}
;
```
A dictionary of translations to customize the UI text and support internationalization.
* `submitButtonTitle`. The submit button title of the search box.
* `resetButtonTitle`. The reset button title search box.
* `noResultsText`. The text to display when searching for facets returns no results.
* `showMoreButtonText`. The text for the "Show more" button.
* `showMoreButtonLabel`. The static accessible name (`aria-label`) for the **Show more** and **Show less** toggle buttons.
This translation is only used when [`showMore`](#param-show-more) is `true`.
Use a label that works for both expanded and collapsed states because this value doesn't change as the button expands or collapses.
```jsx JavaScript icon=code theme={"system"}
;
```
Any `
` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch let you create your own UI for the `` widget with `useRefinementList`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `useRefinementList` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [``](/doc/api-reference/widgets/instantsearch/react) component.
### Usage
First, create your React component:
```jsx JavaScript icon=code theme={"system"}
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:
```jsx JavaScript icon=code theme={"system"}
;
```
### Parameters
Hooks accept parameters. You can either pass them manually or forward props from a custom component.
When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
Arrays and objects are automatically memoized.
The name of the attribute in the records.
To avoid unexpected behavior,
you can't use the same `attribute` prop in a different type of widget.
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
attribute: "categories",
});
```
How the [filters](/doc/api-reference/api-parameters/filters) are combined.
* `'or'`: Returns results matching any of the selected values.
* `'and'`: Returns results matching all selected values.
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
// ...
operator: "and",
});
```
How many facet values to retrieve.
When you set [`showMore`](#param-show-more) and [`showMoreLimit`](#param-show-more-limit),
this is the number of facet values to display before clicking the Show more button.
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
// ...
limit: 5,
});
```
Whether to display a button that expands the number of items.
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
// ...
showMore: true,
});
```
The maximum number of items to display if the widget is showing more items.
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
// ...
showMoreLimit: 20,
});
```
How to sort refinements. Must be one or more of the following strings:
* `"count"` (same as `"count:desc"`)
* `"count:asc"`
* `"count:desc"`
* `"name"` (same as `"name:asc"`)
* `"name:asc"`
* `"name:desc"`
* `"isRefined"` (same as `"isRefined:asc"`)
* `"isRefined:asc"`
* `"isRefined:desc"`
You can also use a sort function that behaves like the standard JavaScript [`compareFunction`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
When you don't set this parameter,
and you've set `facetOrdering` for this facet in `renderingContent`,
facets are sorted using `facetOrdering` and use the default order as a fallback.
In some situations, refined facet values might not be present in the data
returned by Algolia.
```jsx String theme={"system"}
const refinementListApi = useRefinementList({
// ...
sortBy: ["count:desc", "name:asc"],
});
```
```jsx Function theme={"system"}
const sortByName = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function RefinementList() {
const refinementListApi = useRefinementList({
// ...
sortBy,
});
return <>{/* Your JSX */};
}
```
```tsx Function (TypeScript) theme={"system"}
import type { UseRefinementListProps } from "react-instantsearch";
const sortByName: UseRefinementListProps["sortBy"] = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function RefinementList() {
const refinementListApi = useRefinementList({
// ...
sortBy,
});
return <>{/* Your JSX */};
}
```
Escapes the content of the facet values returned by Algolia.
When using this parameter, the highlighting tags are always [`mark`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark).
```jsx JavaScript icon=code theme={"system"}
const refinementListApi = useRefinementList({
// ...
escapeFacetValues: false,
});
```
A function that receives the list of items before they are displayed.
It should return a new array with the same structure.
Use this to transform, filter, or reorder the items.
The function also has access to the full `results` data,
including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```jsx JavaScript theme={"system"}
const transformItems = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function RefinementList() {
const refinementListApi = useRefinementList({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
```tsx TypeScript theme={"system"}
import type { UseRefinementListProps } from 'react-instantsearch';
const transformItems: UseRefinementListProps['transformItems'] = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function RefinementList() {
const refinementListApi = useRefinementList({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
### APIs
Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.
The list of filtering values returned by Algolia.
```ts Type definition theme={"system"}
type RefinementListItem = {
/**
* The value of the refinement list item.
*/
value: string;
/**
* Human-readable value of the refinement list item.
*/
label: string;
/**
* Human-readable value of the searched refinement list item.
*/
highlighted?: string;
/**
* Number of matched results after refinement is applied.
*/
count: number;
/**
* Indicates if the list item is refined.
*/
isRefined: boolean;
};
```
Whether the results are exhaustive.
Creates the next state URL of a selected refinement.
Applies the selected refinement.
Sends an event to the Insights middleware.
Searches for values in the list.
Whether the values are from an search.
Whether a refinement can be applied.
Whether the Show more button can be activated, meaning there are enough
additional items to display, or already displaying over the
[`limit`](/doc/api-reference/widgets/refinement-list/react#param-limit) items.
Whether the menu is displaying all the menu items.
Toggles the number of values displayed between [`limit`](/doc/api-reference/widgets/refinement-list/react#param-limit)
and [`showMoreLimit`](/doc/api-reference/widgets/refinement-list/react#param-show-more-limit).
### Example
```jsx JavaScript theme={"system"}
import React from "react";
import { useRefinementList } from "react-instantsearch";
function CustomRefinementList(props) {
const {
items,
refine,
searchForItems,
canToggleShowMore,
isShowingMore,
toggleShowMore,
} = useRefinementList(props);
return (
<>
searchForItems(event.currentTarget.value)}
/>