API Reference / React InstantSearch / ClearRefinements

ClearRefinements

Signature 
<ClearRefinements
  // Optional parameters
  clearsQuery={boolean}
  transformItems={function}
  translations={object}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The ClearRefinements widget displays a button that lets the user clears every currently applied refinement.

Examples

Copy 
1
2
3

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

<ClearRefinements />

Props

clearsQuery
type: boolean
default: false
Optional

Whether the widget should include the query.
Copy 
1

<ClearRefinements clearsQuery />
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5

<ClearRefinements
  transformItems={items =>
    items.filter(({ attribute }) => attribute !== 'brand')
  }
/>
translations
type: object
Optional

A mapping of keys to translation values.

  • reset: label for the clear refinement button.
Copy 
1
2
3
4
5

<ClearRefinements
  translations={{
    reset: 'Clear all filters',
  }}
/>

HTML output

Copy 
1
2
3
4
5

<div class="ais-ClearRefinements">
  <button class="ais-ClearRefinements-button">
    Clear refinements
  </button>
</div>

When there are no refinements to clear:

Copy 
1
2
3
4
5
6
7
8

<div class="ais-ClearRefinements">
  <button
    class="ais-ClearRefinements-button ais-ClearRefinements-button--disabled"
    disabled
  >
    Clear refinements
  </button>
</div>

Customize the UI with connectCurrentRefinements

If you want to create your own UI of the ClearRefinements widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: CurrentRefinements

It’s a 3-step process:

// 1. Create a React component
const ClearRefinements = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomClearRefinements = connectCurrentRefinements(ClearRefinements);

// 3. Use your connected widget
<CustomClearRefinements />

See code examples

Create a React component

const ClearRefinements = ({ object[] items, function refine }) => {
  // return the DOM output
};

Provided Props

items
type: object[]

The currently applied filters. It is an array of objects with :

  • label: string: the label for the value.
  • attribute: string: the name of the attribute.
  • currentRefinement: any: the raw value of the refinement (depends on the widget).
  • items: object[]: a list of elements in case the refinement accepts multiple values (e.g. RefinementList).
  • value: function: the value to provide to therefine function to clear the refinement.

The value contains the argument to provide to the refine function for removing the refinement, label is for the display. When there are several refinements for the same attribute name, you get a nested items array that contains a label and a value, used to remove a single filter with refine. The attribute and currentRefinement properties are metadata containing the raw values.

Note that clearsQuery still needs to be enabled for the query to be in items.
Copy 
1
2
3
4
5

const ClearRefinements = ({ items, refine }) => (
  <button onClick={() => refine(items)} disabled={!items.length}>
    Clear all refinements
  </button>
);
refine
type: function

Removes the currently applied filters.
Copy 
1
2
3
4
5

const ClearRefinements = ({ items, refine }) => (
  <button onClick={() => refine(items)} disabled={!items.length}>
    Clear all refinements
  </button>
);

Create and instantiate your connected widget

const CustomClearRefinements = connectCurrentRefinements(CurrentRefinements);

<CustomClearRefinements
  // Optional params
  clearsQuery={boolean}
  transformItems={function}
/>

Exposed Props

clearsQuery
type: boolean
Optional

Whether the widget should include the query.
Copy 
1

<CustomClearRefinements clearsQuery />
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5

<CustomClearRefinements
  transformItems={items =>
    items.filter(({ attribute }) => attribute !== 'brand')
  }
/>

Full example

Copy 
1
2
3
4
5
6
7
8
9

import { connectCurrentRefinements } from 'react-instantsearch-dom';

const ClearRefinements = ({ items, refine }) => (
  <button onClick={() => refine(items)} disabled={!items.length}>
    Clear all refinements
  </button>
);

const CustomClearRefinements = connectCurrentRefinements(ClearRefinements);
Did you find this page helpful?
React InstantSearch v6