Skip to main content
The clearRefinements widget provides a button to remove all active filters at once. It’s useful for helping users reset their search and start over.

​
Usage

const clearRefinements = instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
});

search.addWidget(clearRefinements);

​
Examples

​
Basic Clear Button

instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
});

​
With Included Attributes

instantsearch.widgets.clearRefinements({
  container: '#clear-filters',
  includedAttributes: ['brand', 'category', 'price'],
});

​
With Excluded Attributes

instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
  excludedAttributes: ['query'],
});

​
With Custom Template

instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
  templates: {
    resetLabel({ hasRefinements }) {
      return hasRefinements ? 'Clear all filters' : 'No filters applied';
    },
  },
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
includedAttributes
string[]
List of attributes to clear. When provided, only refinements from these attributes are cleared.
​
excludedAttributes
string[]
List of attributes to exclude from being cleared. Useful to preserve certain filters like the search query.
​
transformItems
function
Function to transform the items before clearing.
(items: object[]) => object[]
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<div class="ais-ClearRefinements">
  <button class="ais-ClearRefinements-button" type="button">
    Clear refinements
  </button>
</div>
When disabled (no refinements): 
<div class="ais-ClearRefinements">
  <button
    class="ais-ClearRefinements-button ais-ClearRefinements-button--disabled"
    type="button"
    disabled
  >
    Clear refinements
  </button>
</div>

​
Use Cases

​
Clear All Except Query

instantsearch.widgets.clearRefinements({
  container: '#clear-filters',
  excludedAttributes: ['query'],
  templates: {
    resetLabel: 'Clear filters',
  },
});

​
Clear Only Specific Filters

instantsearch.widgets.clearRefinements({
  container: '#clear-facets',
  includedAttributes: ['brand', 'category', 'color'],
  templates: {
    resetLabel: 'Clear facets',
  },
});

​
With Custom Styling Based on State

instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
  templates: {
    resetLabel({ hasRefinements }) {
      return `
        <span class="${hasRefinements ? 'active' : 'inactive'}">
          ${hasRefinements ? '✕ Clear filters' : 'No active filters'}
        </span>
      `;
    },
  },
});

​
Combine with currentRefinements

Often used together with the currentRefinements widget: 
// Show current refinements
instantsearch.widgets.currentRefinements({
  container: '#current-refinements',
});

// Add clear all button
instantsearch.widgets.clearRefinements({
  container: '#clear-refinements',
});

​
Behavior

The clear button:
  • Is enabled when there are active refinements
  • Is disabled when there are no refinements to clear
  • Clears all refinements when clicked (or only those specified by includedAttributes/excludedAttributes)
  • Does not clear the search query by default (can be changed with includedAttributes)

Build docs developers (and LLMs) love

Get started for freeTalk to us