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 { CurrentRefinements } from "react-instantsearch";
```
Preview this widget and its behavior.
## About this widget
`` is a widget that lets you display the list of active refinements in the search.
You can also create your own UI with [`useCurrentRefinements`](#hook).
## Examples
```jsx JavaScript icon=code theme={"system"}
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 (
);
}
```
## Props
The attributes to include (all by default).
This parameter can't be used with [`excludedAttributes`](/doc/api-reference/widgets/current-refinements/react#param-excluded-attributes).
In the example below, only the `categories` attribute is included.
```jsx JavaScript icon=code theme={"system"}
;
```
The attributes to exclude from the widget.
This parameter can't be used with [`includedAttributes`](/doc/api-reference/widgets/current-refinements/react#param-included-attributes).
In the example below, the `brand` attribute is excluded.
```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.filter((item) => item.attribute !== "brand");
};
function Search() {
return (
);
}
```
```tsx TypeScript theme={"system"}
import type { CurrentRefinementsProps } from "react-instantsearch";
const transformItems: CurrentRefinementsProps["transformItems"] = (items) => {
return items.filter((item) => item.attribute !== "brand");
};
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.
* `list`. The list element.
* `noRefinementList`. The list element when there are no refinements.
* `item`. Each refinement element.
* `label`. The label of each refinement.
* `category`. The container of each refinement's value.
* `categoryLabel`. The text element of each refinement's value.
* `delete`. The delete button of each refinement.
```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 `useCurrentRefinements`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `useCurrentRefinements` 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 { useCurrentRefinements } from "react-instantsearch";
function CustomCurrentRefinements(props) {
const { items, canRefine, refine } = useCurrentRefinements(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 attributes to include (all by default).
This parameter can't be used with [`excludedAttributes`](/doc/api-reference/widgets/current-refinements/react#param-excluded-attributes).
In the example below, only the `categories` attribute is included.
```jsx JavaScript icon=code theme={"system"}
const currentRefinementsApi = useCurrentRefinements({
includedAttributes: ["categories"],
});
```
The attributes to exclude from the widget.
This parameter can't be used with [`includedAttributes`](/doc/api-reference/widgets/current-refinements/react#param-included-attributes).
In the example below, the `brand` attribute is excluded.
```jsx JavaScript icon=code theme={"system"}
const currentRefinementsApi = useCurrentRefinements({
excludedAttributes: ["brand"],
});
```
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.filter((item) => item.attribute !== "brand");
};
function CurrentRefinements() {
const currentRefinementsApi = useCurrentRefinements({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
```tsx TypeScript theme={"system"}
import type { UseCurrentRefinementsProps } from "react-instantsearch";
const transformItems: UseCurrentRefinementsProps["transformItems"] = (
items,
) => {
return items.filter((item) => item.attribute !== "brand");
};
function CurrentRefinements() {
const currentRefinementsApi = useCurrentRefinements({
// ...
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.
All the currently refined items grouped by attribute.
```ts TypeScript icon=code theme={"system"}
type CurrentRefinementsItem = {
/**
* The index name.
*/
indexName: string;
/**
* The index id.
*/
indexId: string;
/**
* The attribute on which the refinement is applied.
*/
attribute: string;
/**
* The textual representation of this attribute.
*/
label: string;
/**
* Currently applied refinements.
*/
refinements: CurrentRefinementsRefinement[];
/**
* Removes the given refinement and triggers a new search.
*/
refine(refinement: CurrentRefinementsRefinement): void;
};
type CurrentRefinementsRefinement = {
/**
* The attribute on which the refinement is applied.
*/
attribute: string;
/**
* The type of the refinement.
*
* It can be one of those: 'facet'|'exclude'|'disjunctive'|'hierarchical'|'numeric'|'query'|'tag'.
*/
type: string;
/**
* The raw value of the refinement.
*/
value: string | number;
/**
* The label of the refinement to display.
*/
label: string;
/**
* The value of the operator (only if applicable).
*/
operator?: string;
/**
* The number of found items (only if applicable).
*/
count?: number;
/**
* Whether the count is exhaustive (only if applicable).
*/
exhaustive?: boolean;
};
```
Whether the search state can be refined.
Clears a single refinement and triggers a new search.
### Example
```jsx JavaScript theme={"system"}
import React from "react";
import { useCurrentRefinements } from "react-instantsearch";
function CustomCurrentRefinements(props) {
const { items, refine } = useCurrentRefinements(props);
return (