UI libraries / Angular InstantSearch / Widgets

ais-current-refinements

Angular InstantSearch isn’t compatible with Angular’s Ivy view engine. We’re investigating how best to support this. For more information and to vote for Algolia’s support of Angular 16 and beyond, see the GitHub issue Algolia Support for Angular InstantSearch

Signature 
<ais-current-refinements
  // Optional parameters
  [includedAttributes]="string[]"
  [excludedAttributes]="string[]"
  [transformItems]="function"
></ais-current-refinements>
Import
Copy 
1
2
3
4
5
6
7
8

import { NgAisCurrentRefinementsModule } from 'angular-instantsearch';

@NgModule({
  imports: [
    NgAisCurrentRefinementsModule,
  ],
})
export class AppModule {}

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

See code examples

About this widget

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

Examples

Copy 
1

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

Props

Parameter Description
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.
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.
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 transforming, removing, or reordering 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

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

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>

Customize the UI with connectCurrentRefinements

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

See code examples

1. Extend the TypedBaseWidget class

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

@Component({
  selector: 'app-current-refinements',
  template: '<p>It works!</p>'
})
export class CurrentRefinements extends TypedBaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('CurrentRefinements');
  }
}

There are a couple of things happening in this boilerplate:

  • create a CurrentRefinements class extending TypedBaseWidget
  • reference the <ais-instantsearch> parent component instance on the CurrentRefinements widget class
  • 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 TypedBaseWidget 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
26
27
28
29
30

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectCurrentRefinements, {
  CurrentRefinementsWidgetDescription,
  CurrentRefinementsConnectorParams
} from 'instantsearch.js/es/connectors/current-refinements/connectCurrentRefinements';

@Component({
  selector: 'app-current-refinements',
  template: '<p>It works!</p>'
})
export class CurrentRefinements extends TypedBaseWidget<CurrentRefinementsWidgetDescription, CurrentRefinementsConnectorParams> {
  public state: CurrentRefinementsWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    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: CurrentRefinementsWidgetDescription['renderState'];
// {
//   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

Parameter Description
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

Parameter Description
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 transforming, removing, or reordering 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).

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
38
39

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectCurrentRefinements, {
  CurrentRefinementsWidgetDescription,
  CurrentRefinementsConnectorParams
} from 'instantsearch.js/es/connectors/current-refinements/connectCurrentRefinements';

@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 TypedBaseWidget<CurrentRefinementsWidgetDescription, CurrentRefinementsConnectorParams> {
  public state: CurrentRefinementsWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('CurrentRefinements');
  }
  ngOnInit() {
    this.createWidget(connectCurrentRefinements, {
      // instance options
    });
    super.ngOnInit();
  }
}
Did you find this page helpful?
Angular InstantSearch v4