ClearRefinements

Lets users reset all applied search refinements.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using 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

JavaScript

import { ClearRefinements } from "react-instantsearch";

View demo

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

JavaScript

import React from "react";
import { liteClient as 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

includedAttributes · 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.

JavaScript

<ClearRefinements includedAttributes={["categories"]} />;

excludedAttributes · 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.

JavaScript

<CurrentRefinements excludedAttributes={["brand"]} />;

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

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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

const transformItems = (items) => {
  return items.filter((item) => item.attribute !== "brand");
};

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

classNames · Partial<ClearRefinementsClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s 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.

JavaScript

<ClearRefinements
  classNames={{
    root: "MyCustomClearRefinements",
    button:
      "MyCustomClearRefinementsButton MyCustomClearRefinementsButton--subclass",
  }}
/>;

translations · Partial<ClearRefinementsTranslations>

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

• resetButtonText. The text for the reset button.

JavaScript

<ClearRefinements
  translations={{
    resetButtonText: "Clear all",
  }}
/>;

...props · React.ComponentProps<'div'>

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

JavaScript

<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. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useClearRefinements } from "react-instantsearch";

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

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

Then, render the widget:

JavaScript

<CustomClearRefinements {...props} />

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() for memoization. Arrays and objects are automatically memoized.

includedAttributes · 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.

JavaScript

const clearRefinementsApi = useClearRefinements({
  includedAttributes: ["categories"],
});

excludedAttributes · 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.

JavaScript

const clearRefinementsApi = useClearRefinements({
  excludedAttributes: ["brand"],
});

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

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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

const 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.

refine · () => void

Clears all the currently refined values and triggers a new search.

canRefine · boolean

Indicates if search state can be refined.

createURL · () => string

Generates a URL of the next state.

Example

JavaScript

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>
  );
}