API Reference / Angular InstantSearch / ais-toggle

ais-toggle

A
Signature 
<ais-toggle
  [attribute]="string"
  [label]="string"

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

About this widget # A

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

Examples # A

Copy 
1
2
3
4

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
></ais-toggle>

Props # A

attribute #
type: string
Required

The name of the attribute on which to apply the refinement.
Copy 
1
2
3
4

<ais-toggle
  attribute="free_shipping"
  label="Free Shipping"
></ais-toggle>
label #
type: string
Required

Label to display for the checkbox.
Copy 
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.
Copy 
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.
Copy 
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# A

Copy 
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 with connectToggleRefinement# A

If you want to create your own UI of the ais-toggle widget, you can combine the connectToggleRefinement 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-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.

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

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;
// }
Copy 
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 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#

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

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?
Angular InstantSearch v4