```ts Signature theme={"system"}
clearRefinements({
container: string | HTMLElement,
// Optional parameters
includedAttributes?: string[],
excludedAttributes?: string[],
templates?: object,
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { clearRefinements } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { clearRefinements } = instantsearch.widgets;
// or directly use instantsearch.widgets.clearRefinements()
```
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
```js JavaScript icon=code theme={"system"}
clearRefinements({
container: "#clear-refinements",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
clearRefinements({
container: "#clear-refinements",
});
```
```js HTMLElement theme={"system"}
clearRefinements({
container: document.querySelector("#clear-refinements"),
});
```
The attributes to include in the refinements to clear (all by default). Can't be used with [`excludedAttributes`](/doc/api-reference/widgets/clear-refinements/js#param-excluded-attributes). In the example below, only the `categories` attribute is included in the refinements to clear.
```js JavaScript icon=code theme={"system"}
clearRefinements({
// ...
includedAttributes: ["categories"],
});
```
The attributes to exclude from the refinements to clear.
Can't be used with [`includedAttributes`](/doc/api-reference/widgets/clear-refinements/js#param-included-attributes).
In the example below, the attribute `brand` is excluded from the refinements to clear.
```js JavaScript icon=code theme={"system"}
clearRefinements({
// ...
excludedAttributes: ["brand"],
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
clearRefinements({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The root element of the widget.
* `button`. The button element.
* `disabledButton`. The button element with disabled state.
```js JavaScript icon=code theme={"system"}
clearRefinements({
// ...
cssClasses: {
root: "MyCustomClearRefinements",
button: [
"MyCustomClearRefinementsButton",
"MyCustomClearRefinementsButton--subclass",
],
},
});
```
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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template for the content of the button.
```js function theme={"system"}
clearRefinements({
// ...
templates: {
resetLabel({ hasRefinements }, { html }) {
return html`${hasRefinements ? "Clear refinements" : "No refinements"}`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
clearRefinements({
// ...
templates: {
resetLabel: "Clear refinements",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## 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.
```js Package manager theme={"system"}
import { connectClearRefinements } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectClearRefinements } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectClearRefinements()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 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).
```js JavaScript icon=code theme={"system"}
const renderClearRefinements = (renderOptions, isFirstRender) => {
const { canRefine, refine, createURL, widgetParams } = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Rendering options
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const renderClearRefinements = (renderOptions, isFirstRender) => {
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#clear-refinements").innerHTML = "";
return;
}
};
```
Clears all the currently refined values and triggers a new search.
```js JavaScript icon=code theme={"system"}
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);
}
};
```
Generates a URL for the next state.
```js JavaScript icon=code theme={"system"}
const renderClearRefinements = (renderOptions, isFirstRender) => {
const { createURL } = renderOptions;
document.querySelector("#clear-refinements").innerHTML = `
Clear refinements
`;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
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`.
```jsx JavaScript icon=code theme={"system"}
const customClearRefinements = connectClearRefinements(
renderClearRefinements
);
search.addWidgets([
customClearRefinements({
// Optional parameters
includedAttributes: string[],
excludedAttributes: string[],
transformItems: function,
})
]);
```
#### Instance options
The attributes to include in the refinements to clear (all by default).
Can't be used with [`excludedAttributes`](/doc/api-reference/widgets/clear-refinements/js#param-excluded-attributes).
In the example below, only the `categories` attribute is included in the refinements to clear.
```js JavaScript icon=code theme={"system"}
customClearRefinements({
includedAttributes: ["categories"],
});
```
The attributes to exclude from the refinements to clear.
Can't be used with [`includedAttributes`](/doc/api-reference/widgets/clear-refinements/js#param-included-attributes).
In the example below, the attribute `brand` is excluded from the refinements to clear.
```js JavaScript icon=code theme={"system"}
customClearRefinements({
excludedAttributes: ["brand"],
});
```
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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
```js JavaScript icon=code theme={"system"}
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 HTML theme={"system"}
```
```js JavaScript theme={"system"}
// 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"),
}),
]);
```