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

ais-current-refinements

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

Widget signature 
<ais-current-refinements
  // Optional parameters
  [includedAttributes]="string[]"
  [excludedAttributes]="string[]"
  [transformItems]="function"
></ais-current-refinements>
See code examples

About this widget #

The ais-current-refinements widget displays a list of refinements applied to the search.

Examples #

Copy
1

<ais-current-refinements></ais-current-refinements>

Props #

includedAttributes #
type: string[]
default: []
Optional

The attributes to include in the widget (all by default). Cannot be used with excludedAttributes. In the example below, only the categories attribute is included in the widget.
Edit
Copy 
1
2
3

<ais-current-refinements
  [includedAttributes]="['categories']"
></ais-current-refinements>
excludedAttributes #
type: string[]
default: ["query"]
Optional

The attributes to exclude from the widget. Cannot be used with includedAttributes. In the example below, the brand attribute is excluded from the widget.
Edit
Copy 
1
2
3

<ais-current-refinements
  [excludedAttributes]="['brand']"
></ais-current-refinements>
transformItems #
type: function
default: items => items
Optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.
Edit
Copy 
1
2
3

<ais-current-refinements
  [transformItems]="transformItems"
></ais-current-refinements>

Customize the UI - connectCurrentRefinements#

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

See code examples

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.

Copy
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-current-refinements',
  template: '<p>It works!</p>'
})
export class CurrentRefinements extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('CurrentRefinements');
  }
}

There are a couple of things happening in this boilerplate:

  • we create a CurrentRefinements class extending BaseWidget
  • we reference the <ais-instantsearch> parent component instance on the CurrentRefinements widget class
  • we set app-current-refinements as a selector, so we can use our component as <app-current-refinements></app-current-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.

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

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectCurrentRefinements } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-current-refinements',
  template: '<p>It works!</p>'
})
export class CurrentRefinements extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('CurrentRefinements');
  }
  ngOnInit() {
    this.createWidget(connectCurrentRefinements, {
      // 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: {
  items: object[];
  refine: Function;
  createURL: Function;
  widgetParams: object;
}
Copy
1
2
3
4
5
6
7
8

<ul>
  <li *ngFor="let item of state.items">
    {{ item.attribute }}:
    <span *ngFor="let refinement of item.refinements">
      {{ refinement.label }}
    </span>
  </li>
</ul>

Rendering options #

items #
type: object[]

All the currently refined items, grouped by attribute.

With each item:

  • attribute: string: the attribute on which the refinement is applied
  • refine: function: removes the refinement
  • refinements: object[]: currently applied refinements

With each refinement:

  • type: 'facet'|'exclude'|'disjunctive'|'hierarchical'|'numeric'|'query': the type of the refinement
  • attribute: string: the attribute on which the refinement is applied
  • label: string: the label of the refinement to display
  • value: string: the raw value of the refinement
  • operator?: string: the value of the operator (only if applicable)
  • exhaustive?: boolean: whether the count is exhaustive (only if applicable)
  • count?: number: the number of found items (only if applicable)
refine #
type: function

Clears a single refinement 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 widget (all by default). Cannot be used with excludedAttributes. In the example below, only the categories attribute is included in the widget.
excludedAttributes #
type: string[]
default: ["query"]
Optional

The attributes to exclude from the widget. Cannot be used with includedAttributes. In the example below, the brand attribute is excluded from the widget.
transformItems #
type: function
default: items => items
Optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.

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
30
31
32
33
34
35
36
37

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectCurrentRefinements } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-current-refinements',
  template: `
<ul>
  <li *ngFor="let item of state.items">
    {{ item.attribute }}:
    <span *ngFor="let refinement of item.refinements">
      {{ refinement.label }}
    </span>
  </li>
</ul>
`
})
export class CurrentRefinements extends BaseWidget {
  public state: {
     items: object[];
     refine: Function;
     createURL: Function;
     widgetParams: object;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('CurrentRefinements');
  }
  ngOnInit() {
    this.createWidget(connectCurrentRefinements, {
      // instance options
    });
    super.ngOnInit();
  }
}

HTML output#

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
30
31
32

<div class="ais-CurrentRefinements">
  <ul class="ais-CurrentRefinements-list">
    <li class="ais-CurrentRefinements-itemt">
      <span class="ais-CurrentRefinements-label">
        Category:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Movies & TV Shows
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Others
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
    <li class="ais-CurrentRefinements-item">
      <span class="ais-CurrentRefinements-label">
        Brand:
      </span>
      <span class="ais-CurrentRefinements-category">
        <span class="ais-CurrentRefinements-categoryLabel">
          Algolia
        </span>
        <button class="ais-CurrentRefinements-delete">✕</button>
      </span>
    </li>
  </ul>
</div>

Did you find this page helpful?

Angular InstantSearch v3