馃帀 Try the public beta of the new docs site at algolia.com/doc-beta! 馃帀
UI libraries / Angular InstantSearch / Widgets

Angular InstantSearch isn鈥檛 compatible with Angular鈥檚 Ivy view engine. We鈥檙e investigating how best to support this. For more information and to vote for Algolia鈥檚 support of Angular 16 and beyond, see the GitHub issue Algolia Support for Angular InstantSearch

Signature
<ais-hits-per-page
  [items]="object[]"
></ais-hits-per-page>
Import
1
2
3
4
5
6
7
8
import { NgAisHitsPerPageModule } from 'angular-instantsearch';

@NgModule({
  imports: [
    NgAisHitsPerPageModule,
  ],
})
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鈥檛 use. Read the Getting started guide for more information.

About this widget

The ais-hits-per-page widget displays a dropdown menu to let the user change the number of displayed hits.

If you only want to configure the number of hits per page without displaying a widget, you can use the ais-configure widget with the hitsPerPage search parameter.

Examples

1
2
3
4
5
6
<ais-hits-per-page
  [items]="[
    { label: '8 hits per page', value: 8, default: true },
    { label: '16 hits per page', value: 16 },
  ]"
></ais-hits-per-page>

Props

Parameter Description
items
type: object[]
Required

List of available options.

1
2
3
4
5
6
<ais-hits-per-page
  [items]="[
    { label: '8 hits per page', value: 8, default: true },
    { label: '16 hits per page', value: 16 },
  ]"
></ais-hits-per-page>

HTML output

1
2
3
4
5
6
<div class="ais-HitsPerPage">
  <select class="ais-HitsPerPage-select">
    <option class="ais-HitsPerPage-option" value="8">8 per page</option>
    <option class="ais-HitsPerPage-option" value="16">16 per page</option>
  </select>
</div>

Customize the UI with connectHitsPerPage

If you want to create your own UI of the ais-hits-per-page widget, you can combine the connectHitsPerPage 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-hits-per-page',
  template: '<p>It works!</p>'
})
export class HitsPerPage extends TypedBaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('HitsPerPage');
  }
}

There are a couple of things happening in this boilerplate:

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

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

import connectHitsPerPage, {
  HitsPerPageWidgetDescription,
  HitsPerPageConnectorParams
} from 'instantsearch.js/es/connectors/hits-per-page/connectHitsPerPage';

@Component({
  selector: 'app-hits-per-page',
  template: '<p>It works!</p>'
})
export class HitsPerPage extends TypedBaseWidget<HitsPerPageWidgetDescription, HitsPerPageConnectorParams> {
  public state: HitsPerPageWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('HitsPerPage');
  }
  ngOnInit() {
    this.createWidget(connectHitsPerPage, {
      // instance options
      items: [
        {value: 6, label: '6 per page', default: true},
        {value: 12, label: '12 per page'},
        {value: 24, label: '24 per page'},
      ],
    });
    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: HitsPerPageWidgetDescription['renderState'];
// {
//   items: object[];
//   canRefine: boolean;
//   refine: Function;
//   widgetParams: object;
// }
1
2
3
4
5
6
7
8
9
<select (change)="state.refine($event.target.value)">
  <option
    *ngFor="let item of state.items"
    [value]="item.value"
    [selected]="item.isRefined"
  >
    {{ item.label }}
  </option>
</select>

Rendering options

Parameter Description
items
type: object[]

The list of items the widget can display, with each item:

  • label: string: the label to display in the option
  • value: number: the number of hits to display per page
  • isRefined: boolean: whether the item is the current refined value
canRefine
type: boolean

Whether the search can be refined.

refine
type: function

Sets the number of hits per page and triggers a search.

widgetParams
type: object

All original widget options forwarded to the render function.

Instance options

Parameter Description
items
type: object[]
Required

The list of available options, with each item:

  • label: string: the label to display in the option
  • value: number: the number of hits to display per page
  • default: boolean: whether this is the default hits per page on first search.
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

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

import connectHitsPerPage, {
  HitsPerPageWidgetDescription,
  HitsPerPageConnectorParams
} from 'instantsearch.js/es/connectors/hits-per-page/connectHitsPerPage';

@Component({
  selector: 'app-hits-per-page',
  template: `
<select (change)="state.refine($event.target.value)">
  <option
    *ngFor="let item of state.items"
    [value]="item.value"
    [selected]="item.isRefined"
  >
    {{ item.label }}
  </option>
</select>
`
})
export class HitsPerPage extends TypedBaseWidget<HitsPerPageWidgetDescription, HitsPerPageConnectorParams> {
  public state: HitsPerPageWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('HitsPerPage');
  }
  ngOnInit() {
    this.createWidget(connectHitsPerPage, {
      // instance options
      items: [
        {value: 6, label: '6 per page', default: true},
        {value: 12, label: '12 per page'},
        {value: 24, label: '24 per page'},
      ],
    });
    super.ngOnInit();
  }
}
Did you find this page helpful?