API Reference / Angular InstantSearch Widgets / ais-pagination
Apr. 24, 2019

ais-pagination

You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.

Widget signature 
<ais-pagination
  // Optional parameters
  [padding]="number"
  [totalPages]="number"
  [showFirst]="boolean"
  [showLast]="boolean"
  [showPrevious]="boolean"
  [showNext]="boolean"
></ais-pagination>
See code examples

About this widget

The ais-pagination widget displays a pagination system allowing the user to change the current page.

Examples

Copy
1

<ais-pagination></ais-pagination>

Props

padding
type: number
default: 3
Optional

How many page links to display around the current page.
Copy 
1

<ais-pagination padding="2"></ais-pagination>
totalPages
type: number
default: Infinity
Optional

The maximum number of pages to display (and to allow navigating to).
Copy 
1

<ais-pagination totalPages="5"></ais-pagination>
showFirst
type: boolean
default: true
Optional

Display the first page link.
Copy 
1

<ais-pagination showFirst="false"></ais-pagination>
showLast
type: boolean
default: true
Optional

Display the last page link.
Copy 
1

<ais-pagination showLast="false"></ais-pagination>
showPrevious
type: boolean
default: true
Optional

Display the previous page link.
Copy 
1

<ais-pagination showPrevious="false"></ais-pagination>
showNext
type: boolean
default: true
Optional

Display the next page link.
Copy 
1

<ais-pagination showNext="false"></ais-pagination>
class-names
default: {}
Optional
Copy 
1
2
3
4
5
6
7

<ais-pagination
  :class-names="{
    'ais-Pagination': 'MyCustomPagination',
    'ais-Pagination-list': 'MyCustomPaginationList',
    // ...
  }"
></ais-pagination>

Customize the UI - connectPagination

If you want to create your own UI of the ais-pagination widget, you can combine the connectPagination connector with the BaseWidget class.

See code examples

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.

Copy
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-pagination',
  template: '<p>It works!</p>'
})
export class Pagination extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('Pagination');
  }
}

There are a couple of things happening in this boilerplate:

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

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.

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

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectPagination } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-pagination',
  template: '<p>It works!</p>'
})
export class Pagination extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('Pagination');
  }
  ngOnInit() {
    this.createWidget(connectPagination, {
      // 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: {
  pages: number[];
  currentRefinement: number;
  nbHits: number;
  nbPages: number;
  isFirstPage: boolean;
  isLastPage: boolean;
  refine: Function;
  createURL: Function;
  widgetParams: Function;
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<button
  (click)="state.refine(state.currentRefinement - 1)"
  [disabled]="state.isFirstPage"
>
  Prev
</button>
<button *ngFor="let page of state.pages" (click)="state.refine(page)">
  <strong *ngIf="page === state.currentRefinement">{{ page + 1 }}</strong>
  <span *ngIf="page !== state.currentRefinement">{{ page + 1 }}</span>
</button>
<button
  (click)="state.refine(state.currentRefinement + 1)"
  [disabled]="state.isLastPage"
>
  Next
</button>

If SEO is critical to your search page, your custom HTML markup needs to be parsable:

  • use plain <a> tags with href attributes for search engines bots to follow them,
  • use semantic markup with structured data when relevant, and test it.

Refer to our SEO checklist for building SEO-ready search experiences.

Rendering options

pages
type: number[]

The pages relevant to the current state and padding.
currentRefinement
type: number

The number of the currently displayed page.
nbHits
type: number

The computed number of hits for the last query (can be approximate).
nbPages
type: number

The number of pages for the result set.
isFirstPage
type: boolean

Whether the current page is also the first one.
isLastPage
type: boolean

Whether the current page is also the last one.
refine
type: function

Sets the current page and triggers a search.
createURL
type: function

Generates a URL for the next state. The number is the page to generate the URL for.
widgetParams
type: function

All original widget options forwarded to the render function.

Instance options

totalPages
type: number
Optional

The total number of pages to browse.
padding
type: number
default: 3
Optional

The padding of pages to show around the current page.

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
40
41
42
43
44
45
46
47
48
49
50

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectPagination } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-pagination',
  template: `
<button
  (click)="state.refine(state.currentRefinement - 1)"
  [disabled]="state.isFirstPage"
>
  Prev
</button>
<button *ngFor="let page of state.pages" (click)="state.refine(page)">
  <strong *ngIf="page === state.currentRefinement">{{ page + 1 }}</strong>
  <span *ngIf="page !== state.currentRefinement">{{ page + 1 }}</span>
</button>
<button
  (click)="state.refine(state.currentRefinement + 1)"
  [disabled]="state.isLastPage"
>
  Next
</button>
`
})
export class Pagination extends BaseWidget {
  public state: {
     pages: number[];
     currentRefinement: number;
     nbHits: number;
     nbPages: number;
     isFirstPage: boolean;
     isLastPage: boolean;
     refine: Function;
     createURL: Function;
     widgetParams: Function;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('Pagination');
  }
  ngOnInit() {
    this.createWidget(connectPagination, {
      // instance options
    });
    super.ngOnInit();
  }
}

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

<div class="ais-Pagination">
  <ul class="ais-Pagination-list">
    <li class="ais-Pagination-item ais-Pagination-item--firstPage ais-Pagination-item--disabled">
      <span class="ais-Pagination-link" aria-label="First">‹‹</span>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--previousPage ais-Pagination-item--disabled">
      <span class="ais-Pagination-link" aria-label="Previous">‹</span>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--selected">
      <a class="ais-Pagination-link" href="#">1</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">2</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--page">
      <a class="ais-Pagination-link" href="#">3</a>
    </li>
    <li class="ais-Pagination-item">
      <a class="ais-Pagination-link" href="#">4</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--nextPage">
      <a class="ais-Pagination-link" aria-label="Next" href="#">›</a>
    </li>
    <li class="ais-Pagination-item ais-Pagination-item--lastPage">
      <a class="ais-Pagination-link" aria-label="Last" href="#">››</a>
    </li>
  </ul>
</div>

Did you find this page helpful?

Angular InstantSearch v3