🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / InstantSearch.js / Widgets

clearRefinements

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

import { clearRefinements } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

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

Examples

Copy 
1
2
3

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

Options

Parameter Description
container
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Copy 
1
2
3

clearRefinements({
  container: '#clear-refinements',
});
includedAttributes
type: string[]
default: []
Optional

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.
Copy 
1
2
3
4

clearRefinements({
  // ...
  includedAttributes: ['categories'],
});
excludedAttributes
type: string[]
default: ["query"]
Optional

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.
Copy 
1
2
3
4

clearRefinements({
  // ...
  excludedAttributes: ['brand'],
});
templates
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

clearRefinements({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: object
default: {}
Optional

The CSS classes you can override:

  • root: the root element of the widget.
  • button: the button element.
  • disabledButton: the button element with disabled state.
Copy 
1
2
3
4
5
6
7
8
9
10

clearRefinements({
  // ...
  cssClasses: {
    root: 'MyCustomClearRefinements',
    button: [
      'MyCustomClearRefinementsButton',
      'MyCustomClearRefinementsButton--subclass',
    ],
  },
});
transformItems
type: function
default: items => items
Optional

Receives the items to clear, and is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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 the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
resetLabel
type: string|function
Optional

The template for the content of the button.
Copy 
1
2
3
4
5
6
7
8

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

HTML output

Copy 
1
2
3
4
5

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

Copy 
1

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

Then it’s a 3-step process:

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

See code examples

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

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

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

  // Render the widget
}

Rendering options

Parameter Description
canRefine
type: boolean
Required

Indicates if search state can be refined.
Copy 
1
2
3
4
5
6
7
8

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

  if (!canRefine) {
    document.querySelector('#clear-refinements').innerHTML = '';
    return;
  }
};
refine
type: function

Clears all the currently refined values and triggers a new search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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
type: function

Generates a URL for the next state.
Copy 
1
2
3
4
5
6
7

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

  document.querySelector('#clear-refinements').innerHTML = `
    <a href=${createURL()}>Clear refinements</a>
  `;
};
widgetParams
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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

  widgetParams.container.innerHTML = '...';
};

// ...

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

Create and instantiate the custom widget

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customClearRefinements = connectClearRefinements(
  renderClearRefinements
);

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

Instance options

Parameter Description
includedAttributes
type: string[]
default: []
Optional

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.
Copy 
1
2
3

customClearRefinements({
  includedAttributes: ['categories'],
});
excludedAttributes
type: string[]
default: ["query"]
Optional

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.
Copy 
1
2
3

customClearRefinements({
  excludedAttributes: ['brand'],
});
transformItems
type: function
default: items => items
Optional

Receives the items to clear, and is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// 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'),
  })
]);
Did you find this page helpful?
InstantSearch.js v4