API Reference / React InstantSearch Hooks / <ClearRefinements>

<ClearRefinements>

A
Signature 
<ClearRefinements
  // Optional props
  includedAttributes={string[]}
  excludedAttributes={string[]}
  transformItems={ClearRefinementsProps['transformItems']}
  classNames={Partial<ClearRefinementsClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

About this widget # A

<ClearRefinements> is a widget that resets the active refinements of the search.

You can control which attributes are cleared with the props.

You can also create your own UI with useClearRefinements().

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, ClearRefinements } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <ClearRefinements />
    </InstantSearch>
  );
}

Props # A

includedAttributes #
type: string[]
default: []

The attributes to include in the refinements to clear (all by default). Can’t be used with excludedAttributes. In the example below, only the categories attribute is included in the refinements to clear.
Copy 
1

<ClearRefinements includedAttributes={['categories']} />
excludedAttributes #
type: string[]
default: ["query"]

The attributes to exclude from the refinements to clear. Can’t be used with includedAttributes. In the example below, the attribute brand is excluded from the refinements to clear.
Copy 
1

<CurrentRefinements excludedAttributes={['brand']} />
transformItems #
type: ClearRefinementsProps['transformItems']
Optional

Function which receives the items to clear, which is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10

<ClearRefinements
  transformItems={(items) => items.filter((item) => item !== 'brand')}

  /* or, combined with results */
  transformItems={(items, { results }) => {
    return results.nbHits === 0
      ? items
      : items.filter(item => item !== 'brand');
  }}
/>
classNames #
type: Partial<ClearRefinementsClassNames>
Optional

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • button: The button element.
  • disabledButton: The button element when there are no refinements to clear.
Copy 
1
2
3
4
5
6

<ClearRefinements
  classNames={{
    root: 'MyCustomClearRefinements',
    button: 'MyCustomClearRefinementsButton MyCustomClearRefinementsButton--subclass',
  }}
/>
...props #
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1

<ClearRefinements className="MyCustomClearRefinements" title="My custom title" />

Hook# A

React InstantSearch Hooks let you create your own UI for the <ClearRefinements> widget with useClearRefinements(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useClearRefinements() Hook accepts parameters and returns APIs.

See code examples

Usage#

First, create your React component:

import { useClearRefinements } from 'react-instantsearch-hooks-web';

function CustomClearRefinements(props) {
  const { refine, canRefine, createURL } = useClearRefinements(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

<CustomClearRefinements {...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 with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

includedAttributes #
type: string[]
default: []

The attributes to include in the refinements to clear (all by default). Can’t be used with excludedAttributes. In the example below, only the categories attribute is included in the refinements to clear.
Copy 
1
2
3

const clearRefinementsApi = useClearRefinements({
  includedAttributes: ['categories'],
});
excludedAttributes #
type: string[]
default: ["query"]

The attributes to exclude from the refinements to clear. Can’t be used with includedAttributes. In the example below, the attribute brand is excluded from the refinements to clear.
Copy 
1
2
3

const clearRefinementsApi = useClearRefinements({
  excludedAttributes: ['brand'],
});
transformItems #
type: UseClearRefinementsProps['transformItems']
Optional

Function which receives the items to clear, which is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const clearRefinementsApi = useClearRefinements({
  transformItems(items) {
    return items.filter((item) => item !== 'brand');
  },

  /* or, combined with results */
  transformItems(items, { results }) {
    return results.nbHits === 0
      ? items
      : items.filter(item => item !== 'brand');
  },
});

APIs#

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

refine #
type: () => void

Clears all the currently refined values and triggers a new search.
canRefine #
type: boolean

Indicates if search state can be refined.
createURL #
type: () => string

Generates a URL of the next state.

Example#

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useClearRefinements } from 'react-instantsearch-hooks-web';

function CustomClearRefinements(props) {
  const { canRefine, refine } = useClearRefinements(props);

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6