UI libraries / React InstantSearch / Widgets

Dec. 04, 2023

<ClearRefinements>

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.

Signature

<ClearRefinements
  // Optional props
  includedAttributes={string[]}
  excludedAttributes={string[]}
  transformItems={function}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

Copy

1
import { ClearRefinements } from 'react-instantsearch';

See code examples

See live example

About this widget

<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

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

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

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

Props

Parameter Description


            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
<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
<CurrentRefinements excludedAttributes={['brand']} />


            transformItems

type: (items: object[], metadata: { results: SearchResults }) => object[]

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 transformItems = (items) => {
  return items.filter((item) => item.attribute !== 'brand');
};

function Search() {
  return (
    <ClearRefinements
      // ...
      transformItems={transformItems}
    />
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import type { ClearRefinementsProps } from 'react-instantsearch';

const transformItems: ClearRefinementsProps['transformItems'] = (items) => {
  return items.filter((item) => item.attribute !== 'brand');
};

function Search() {
  return (
    <ClearRefinements
      // ...
      transformItems={transformItems}
    />
  );
}


            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
<ClearRefinements
  classNames={{
    root: 'MyCustomClearRefinements',
    button: 'MyCustomClearRefinementsButton MyCustomClearRefinementsButton--subclass',
  }}
/>


            translations

type: Partial<ClearRefinementsTranslations>

Optional

A dictionary of translations to customize the UI text and support internationalization.

resetButtonText: The text for the reset button.

Copy
<ClearRefinements
  translations={{
    resetButtonText: 'Clear all',
  }}
/>


            ...props

type: React.ComponentProps<'div'>

Optional

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

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

Hook

React InstantSearch 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';

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 to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

Parameter Description


            includedAttributes

type: string[]

default: []

Copy
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
const clearRefinementsApi = useClearRefinements({
  excludedAttributes: ['brand'],
});


            transformItems

type: (items: string[], metadata: { results: SearchResults }) => string[]

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 transformItems = (items) => {
  return items.filter((item) => item !== 'brand');
};

function ClearRefinements() {
  const clearRefinementsApi = useClearRefinements({
    // ...
    transformItems,
  });

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import type { UseClearRefinementsProps } from 'react-instantsearch';

const transformItems: UseClearRefinementsProps['transformItems'] = (items) => {
  return items.filter((item) => item !== 'brand');
};

function ClearRefinements() {
  const clearRefinementsApi = useClearRefinements({
    // ...
    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.

Parameter	Description
`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
9
10
11
12
import React from 'react';
import { useClearRefinements } from 'react-instantsearch';

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

  return (
    <button disabled={!canRefine} onClick={refine}>
      Clear refinements
    </button>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import React from 'react';
import {
  useClearRefinements,
  UseClearRefinementsProps,
} from 'react-instantsearch';

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

  return (
    <button disabled={!canRefine} onClick={refine}>
      Clear refinements
    </button>
  );
}

Did you find this page helpful?

<ClearRefinements>

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example

On this page