clearRefinements

Lets users reset all applied search refinements.

Signature

clearRefinements({
  container: string | HTMLElement,
  // Optional parameters
  includedAttributes?: string[],
  excludedAttributes?: string[],
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

Package manager

import { clearRefinements } from "instantsearch.js/es/widgets";

const { clearRefinements } = instantsearch.widgets;
// or directly use instantsearch.widgets.clearRefinements()

See this widget in action

Preview this widget and its behavior.

About this widget

The clearRefinements widget displays a button that lets users clean every refinement applied to the search. You can control which attributes are impacted by the button with the options.

Examples

JavaScript

clearRefinements({
  container: "#clear-refinements",
});

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

clearRefinements({
  container: "#clear-refinements",
});

clearRefinements({
  container: document.querySelector("#clear-refinements"),
});

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

clearRefinements({
  // ...
  excludedAttributes: ["brand"],
});

templates · object

The templates to use for the widget.

JavaScript

clearRefinements({
  // ...
  templates: {
    // ...
  },
});

cssClasses · object · default: "{}"

The CSS classes you can override:

• root. The root element of the widget.
• button. The button element.
• disabledButton. The button element with disabled state.

JavaScript

clearRefinements({
  // ...
  cssClasses: {
    root: "MyCustomClearRefinements",
    button: [
      "MyCustomClearRefinementsButton",
      "MyCustomClearRefinementsButton--subclass",
    ],
  },
});

transformItems · function · default: "items => items"

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

clearRefinements({
  // ...
  transformItems(items) {
    return items.filter((item) => item !== "brand");
  },
});

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

Templates

You can customize parts of a widget’s UI using the Templates API.

Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

resetLabel · string | function

The template for the content of the button.

function

clearRefinements({
  // ...
  templates: {
    resetLabel({ hasRefinements }, { html }) {
      return html`<span
        >${hasRefinements ? "Clear refinements" : "No refinements"}</span
      >`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
clearRefinements({
  // ...
  templates: {
    resetLabel: "Clear refinements",
  },
});

HTML output

HTML

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

Customize the UI with connectClearRefinements

If you want to create your own UI of the clearRefinements widget, you can use connectors.

To use connectClearRefinements, you can import it with the declaration relevant to how you installed InstantSearch.js.

Package manager

import { connectClearRefinements } from "instantsearch.js/es/connectors";

const { connectClearRefinements } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectClearRefinements()

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderClearRefinements = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customClearRefinements = connectClearRefinements(renderClearRefinements);

// 3. Instantiate
search.addWidgets([
  customClearRefinements({
    // instance params
  }),
]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { canRefine, refine, createURL, widgetParams } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

Rendering options

canRefine · boolean · required

Indicates if search state can be refined.

JavaScript

const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#clear-refinements").innerHTML = "";
    return;
  }
};

refine · function

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

JavaScript

const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { refine } = renderOptions;

  const container = document.querySelector("#clear-refinements");

  if (isFirstRender) {
    const button = document.createElement("button");
    button.textContent = "Clear refinements";

    button.addEventListener("click", () => {
      refine();
    });

    container.appendChild(button);
  }
};

createURL · function

Generates a URL for the next state.

JavaScript

const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { createURL } = renderOptions;

  document.querySelector("#clear-refinements").innerHTML = `
    <a href=${createURL()}>Clear refinements</a>
  `;
};

widgetParams · object

All original widget options forwarded to the render function.

JavaScript

const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customClearRefinements({
    container: document.querySelector("#clear-refinements"),
  }),
]);

Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters.

There are two kinds of parameters you can pass:

• Instance parameters. Predefined options that configure Algolia’s behavior.
• Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customClearRefinements = connectClearRefinements(
  renderClearRefinements
);

search.addWidgets([
  customClearRefinements({
    // Optional parameters
    includedAttributes: string[],
    excludedAttributes: string[],
    transformItems: function,
  })
]);

Instance options

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

customClearRefinements({
  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

customClearRefinements({
  excludedAttributes: ["brand"],
});

transformItems · function · default: "items => items"

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

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

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

Full example

HTML

<div id="clear-refinements"></div>

// Create the render function
const renderClearRefinements = (renderOptions, isFirstRender) => {
  const { canRefine, refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    const button = document.createElement("button");
    button.textContent = "Clear refinements";

    button.addEventListener("click", () => {
      refine();
    });

    widgetParams.container.appendChild(button);
  }

  widgetParams.container.querySelector("button").disabled = !canRefine;
};

// Create the custom widget
const customClearRefinements = connectClearRefinements(renderClearRefinements);

// Instantiate the custom widget
search.addWidgets([
  customClearRefinements({
    container: document.querySelector("#clear-refinements"),
  }),
]);