ais-toggle
You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.
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. |
||
|
Copy
|
|||
label
|
type: string
Required
Label to display for the checkbox. |
||
|
Copy
|
|||
on
|
type: boolean|number|string
default: true
Optional
The value of the refinement to apply on the attribute when checked. |
||
|
Copy
|
|||
off
|
type: boolean|number|string
Optional
The value of the refinement to apply on the attribute when unchecked. |
||
|
Copy
|
|||
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 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-toggle-refinement',
template: '<p>It works!</p>'
})
export class ToggleRefinement extends BaseWidget {
constructor(
@Inject(forwardRef(() => NgAisInstantSearch))
public instantSearchParent
) {
super('ToggleRefinement');
}
}
There are a couple of things happening in this boilerplate:
- we create a
ToggleRefinementclass extendingBaseWidget - we reference the
<ais-instantsearch>parent component instance on theToggleRefinementwidget class - we set
app-toggle-refinementas a selector, so we can use our component as<app-toggle-refinement></app-toggle-refinement>
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
26
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectToggleRefinement } from 'instantsearch.js/es/connectors';
@Component({
selector: 'app-toggle-refinement',
template: '<p>It works!</p>'
})
export class ToggleRefinement extends BaseWidget {
public state: {
// render options
};
constructor(
@Inject(forwardRef(() => NgAisInstantSearch))
public instantSearchParent
) {
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: {
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:
|
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
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectToggleRefinement } from 'instantsearch.js/es/connectors';
@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 BaseWidget {
public state: {
value: object;
refine: Function;
createURL: Function;
widgetParams: object;
};
constructor(
@Inject(forwardRef(() => NgAisInstantSearch))
public instantSearchParent
) {
super('ToggleRefinement');
}
ngOnInit() {
this.createWidget(connectToggleRefinement, {
// instance options
attribute: 'free_shipping',
});
super.ngOnInit();
}
}
