API Reference / InstantSearch.js Widgets / clearRefinements
Apr. 24, 2019

clearRefinements

Widget signature 
instantsearch.widgets.clearRefinements({
  container: string|HTMLElement,
  // Optional parameters
  includedAttributes: string[],
  excludedAttributes: string[],
  templates: object,
  cssClasses: object,
  transformItems: function,
});
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

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

Options #

container #
type: string|HTMLElement
Required

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

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

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

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

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

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

The CSS classes to override.

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

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

Function which receives the items to clear, which is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.
Edit
Copy 
1
2
3
4
5
6

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

Templates #

resetLabel #
type: string|function
Optional

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

instantsearch.widgets.clearRefinements({
  // ...
  templates: {
    resetLabel: 'Clear refinements',
  },
});

Customize the UI - connectClearRefinements#

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

It’s a 3-step process:

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

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

// 3. Instantiate
search.addWidget(
  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 hasRefinements,
    function refine,
    function createURL,
    object widgetParams,
  } = renderOptions;

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

  // Render the widget
}

Rendering options #

hasRefinements #
type: boolean

Indicates if there are currently applied refinements.
Copy
1
2
3
4
5
6
7

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

  document.querySelector('#clear-refinements').innerHTML = `
    <button ${!hasRefinements ? 'disabled' : ''}>Clear refinements</button>
  `;
};
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.addWidget(
  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 = instantsearch.connectors.connectClearRefinements(
  renderClearRefinements
);

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

Instance options #

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

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

Function which receives the items to clear, which is called before clearing them. Should return a new array with the same shape as the original array. Useful for filtering items.
Edit
Copy 
1
2
3
4
5

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

Full example#

Edit
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 { hasRefinements, 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 = !hasRefinements;
};

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

// Instantiate the custom widget
search.addWidget(
  customClearRefinements({
    container: document.querySelector('#clear-refinements'),
  })
);

HTML output#

Copy
1
2
3
4
5

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

Did you find this page helpful?

InstantSearch.js v3