API Reference / Angular InstantSearch Widgets / ais-toggle
Widget signature
<ais-toggle
  [attribute]="string"
  [label]="string"

  // Optional parameters
  [on]="boolean|number|string"
  [off]="boolean|number|string"
></ais-toggle>

About this widget

The ais-toggle widget provides an on / off filtering feature based on an attribute value.

Examples

1
2
3
4
<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
></ais-toggle>

Props

attribute
type: string
Required

The name of the attribute on which to apply the refinement.

1
2
3
4
<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
></ais-toggle>
label
type: string
Required

Label to display for the checkbox.

1
2
3
4
<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
></ais-toggle>
on
type: boolean|number|string
default: true
Optional

The value of the refinement to apply on the attribute when checked.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  on="yes"
></ais-toggle>

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  [on]="true"
></ais-toggle>

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  [on]="1"
></ais-toggle>
off
type: boolean|number|string
Optional

The value of the refinement to apply on the attribute when unchecked.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  off="no"
></ais-toggle>

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  [off]="false"
></ais-toggle>

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
  [off]="0"
></ais-toggle>

HTML output

1
2
3
4
5
6
7
<div class="ais-ToggleRefinement">
  <label class="ais-ToggleRefinement-label">
    <input class="ais-ToggleRefinement-checkbox" type="checkbox" />
    <span class="ais-ToggleRefinement-labelText">Free Shipping</span>
    <span class="ais-ToggleRefinement-count">18,013</span>
  </label>
</div>

Customize the UI - connectToggleRefinement

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

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.

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-toggle-refinement',
  template: '<p>It works!</p>'
})
export class ToggleRefinement extends TypedBaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('ToggleRefinement');
  }
}

There are a couple of things happening in this boilerplate:

  • create a ToggleRefinement class extending TypedBaseWidget
  • reference the <ais-instantsearch> parent component instance on the ToggleRefinement widget class
  • set app-toggle-refinement as a selector, so we can use our component as <app-toggle-refinement></app-toggle-refinement>

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.

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
import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectToggleRefinement, {
  ToggleRefinementWidgetDescription,
  ToggleRefinementConnectorParams
} from 'instantsearch.js/es/connectors/toggle-refinement/connectToggleRefinement';

@Component({
  selector: 'app-toggle-refinement',
  template: '<p>It works!</p>'
})
export class ToggleRefinement extends TypedBaseWidget<ToggleRefinementWidgetDescription, ToggleRefinementConnectorParams> {
  public state: ToggleRefinementWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('ToggleRefinement');
  }
  ngOnInit() {
    this.createWidget(connectToggleRefinement, {
      // instance options
      attribute: 'free_shipping',
    });
    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: ToggleRefinementWidgetDescription['renderState'];
// {
//   value: object;
//   refine: Function;
//   createURL: Function;
//   widgetParams: object;
// }
1
2
3
4
<label *ngIf="state.value">
  <input type="checkbox" [checked]="state.value.isRefined" (click)="state.refine(state.value)"/>
  Free shipping {{ state.value.count }}
</label>

Rendering options

value
type: object

The current refinement, with:

  • isRefined: boolean: whether or not the checkbox is checked.
  • count: number: the number of results after the refinement was applied.
  • onFacetValue: object: the value for the attribute. It contains count (useful to get the raw value of the count).
  • offFacetValue: object: the value for the attribute. It contains count (useful to get the raw value of the count).
refine
type: function

Updates to the next state by applying the toggle refinement.

createURL
type: function

Generates a URL for the next state.

widgetParams
type: object

All original widget options forwarded to the render function.

Instance options

attribute
type: string
Required

The name of the attribute on which to apply the refinement.

on
type: boolean|number|string
default: true
Optional

The value of the refinement to apply on the attribute when checked.

off
type: boolean|number|string
Optional

The value of the refinement to apply on the attribute when unchecked.

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
31
32
33
34
35
36
import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectToggleRefinement, {
  ToggleRefinementWidgetDescription,
  ToggleRefinementConnectorParams
} from 'instantsearch.js/es/connectors/toggle-refinement/connectToggleRefinement';

@Component({
  selector: 'app-toggle-refinement',
  template: `
<label *ngIf="state.value">
  <input type="checkbox" [checked]="state.value.isRefined" (click)="state.refine(state.value)"/>
  Free shipping {{ state.value.count }}
</label>
`
})
export class ToggleRefinement extends TypedBaseWidget<ToggleRefinementWidgetDescription, ToggleRefinementConnectorParams> {
  public state: ToggleRefinementWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('ToggleRefinement');
  }
  ngOnInit() {
    this.createWidget(connectToggleRefinement, {
      // instance options
      attribute: 'free_shipping',
    });
    super.ngOnInit();
  }
}

Did you find this page helpful?