API Reference / Angular InstantSearch Widgets / ais-clear-refinements
Apr. 24, 2019

ais-clear-refinements

You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.

Widget signature
<ais-clear-refinements
  // Optional parameters
  [includedAttributes]="string[]"
  [excludedAttributes]="string[]"
  [autoHideContainer]="boolean"
></ais-clear-refinements>

About this widget

The ais-clear-refinements widget displays a button that lets the user clean every refinement applied to the search.

Examples

1
<ais-clear-refinements></ais-clear-refinements>

Props

excludedAttributes
type: string[]
default: ["query"]
Optional

The attributes to exclude from the refinements to clear. In the example below, the attribute brand is excluded from the refinements to clear.

1
2
3
<ais-clear-refinements
  [excludedAttributes]="['brand']"
></ais-clear-refinements>
includedAttributes
type: string[]
default: []
Optional

The attributes to include in the refinements to clear (all by default). In the example below, only the query and categories attributes are included in the refinements to clear.

1
2
3
<ais-clear-refinements
  [includedAttributes]=['query', 'categories']
></ais-clear-refinements>
autoHideContainer
type: boolean
default: false
Optional

Hides the widget if there’s no refinements to display

1
2
3
<ais-clear-refinements
  [autoHideContainer]="true"
></ais-clear-refinements>

Customize the UI - connectClearRefinements

If you want to create your own UI of the ais-clear-refinements widget, you can combine the connectClearRefinements connector with the BaseWidget class.

1. Extend the BaseWidget class

First of all, you will need to write some boilerplate code in order to initialize correctly the BaseWidget class. This happens in the constructor() of your class extending the BaseWidget class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';

@Component({
  selector: 'app-clear-refinements',
  template: '<p>It works!</p>'
})
export class ClearRefinements extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('ClearRefinements');
  }
}

There are a couple of things happening in this boilerplate:

  • we create a ClearRefinements class extending BaseWidget
  • we reference the <ais-instantsearch> parent component instance on the ClearRefinements widget class
  • we set app-clear-refinements as a selector, so we can use our component as <app-clear-refinements></app-clear-refinements>

2. Connect your custom widget

The BaseWidget class has a method called createWidget() which takes two arguments: the connector to use and an object of options (instance options) for this connector. We call this method at ngOnInit. This component now implements OnInit.

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
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectClearRefinements } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-clear-refinements',
  template: '<p>It works!</p>'
})
export class ClearRefinements extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('ClearRefinements');
  }
  ngOnInit() {
    this.createWidget(connectClearRefinements, {
      // instance options
    });
    super.ngOnInit();
  }
}

3. Render from the state

Your component instance has access to a this.state property which holds the rendering options of the widget.

public state: {
  hasRefinements: boolean;
  refine: Function;
  createURL: Function;
  widgetParams: object;
}
1
<button (click)="state.refine()"> Clear all </button>

Rendering options

hasRefinements
type: boolean

Whether there are currently applied refinements.

refine
type: function

Clears all the currently refined values and triggers a new search.

createURL
type: function

Generates a URL for the next state.

widgetParams
type: object

All original widget options forwarded to the render 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.

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.

transformItems
type: function
default: x => x
Optional

Receives the items to clear, and is called before clearing them. Returns a new array with the same shape as the original array. This is useful for filtering items.

Full example

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
30
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectClearRefinements } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-clear-refinements',
  template: `
<button (click)="state.refine()"> Clear all </button>
`
})
export class ClearRefinements extends BaseWidget {
  public state: {
     hasRefinements: boolean;
     refine: Function;
     createURL: Function;
     widgetParams: object;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('ClearRefinements');
  }
  ngOnInit() {
    this.createWidget(connectClearRefinements, {
      // instance options
    });
    super.ngOnInit();
  }
}

HTML output

1
2
3
4
5
<div class="ais-ClearRefinements">
  <button class="ais-ClearRefinements-button">
    Clear refinements
  </button>
</div>

Did you find this page helpful?