UI libraries / InstantSearch.js / Widgets

clearRefinements

A
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 # A

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 # A

Copy 
1
2
3

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

Options # A

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 # A

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# A

Copy 
1
2
3
4
5

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

Customize the UI with connectClearRefinements# A

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