Understanding Pagination control from PnP reusable React controls

Introduction

Proceeding with the appointments with the PnP React controls today I want to talk about the Pagination control.

If you’re interested you can find the code of this sample here.

The control is used to display a pagination control and allows the navigation between the different available pages.

Visual appearance

Let’s start with some details of the control visual appearance

Using the minimal configuration the appearance is the following:

As you can see there are the page numbers and other buttons available.

The buttons at the start and end of the control are used to navigate to the first or to the last page.

The dots are used to navigate to the next (or previous) set of pages.

Now that we have a minimal understanding of the control itself let’s have a look at how the sample solution appears:

The control also support the theme used in the current site. For example using a different theme the appearance would be the following:

Now let’s cover a little bit more in detail the different instances.

The minimal configuration is the control instance with the minimal configuration required.

By default, the control displays the first and last page jump alongside the limiter icon. It also shows a default of three pages between the selected one and the limiter icon. To clarify the number of showed pages here is another screenshot:

To understand what is the number of showed items, the limiter instance, shows how it would display with the limiter property set to 1 element:

The hide page jump instance shows that’s possible to hide the first and last page buttons.

An additional helpful feature is the ability to change the limiter icon. For example, in the next screenshot, I’ve set the Fluent UI icon to a circle with a plus inside it. It’s possible to define an icon from the Fluent UI icon set.

After understanding what’s the look of the UI let’s understand a little bit more about the code.

Show me the code

Base knowledge for the sample

If you want to understand a little bit how the sample solution works, this chapter is for you. Otherwise, just skip to the next one.

Each of the instances call the _getPage method. This method updates the currently selected page in the state of the component.

private _getPage(page: number): void {
  this.setState({ currentPage: page });
}

To show how the control can be used there are also a _getItems method and also a _renderItems. Those methods are used only to display a set of 100 items.

Finally, there is the _getPageCount method. It returns the number of available pages. This number is customizable using the web part’s property pane.

Install and import the control

To use the PnP React controls, first you need to install the package:

npm install @pnp/spfx-controls-react --save --save-exact

After the installation of the package you can proceed with the following instructions to use the Pagination control.

---

To use the control you first need to import it and that can be done as following:

import { Pagination } from "@pnp/spfx-controls-react/lib/pagination";

Now let’s cover a little bit more in detail the control instances.

Minimal instance

The following is the minimal instance of the control, this means that this contains only the required properties.

<Pagination
  currentPage={this.state.currentPage}
  totalPages={this._getPageCount()}
  onChange={(page) => this._getPage(page)} />

Digging a little bit more in the properties:

• currentPage: accept a number and that is the currently selected page. This value is a 1-index value.
• totalPages: is a number displaying the total number of pages to be shown.
• onChange: is a method used to retrieve the currently selected page number.

All the properties set in this instance will be used in all the other instances.

Limiter instance

The limiter property accepts a number value. This number sets how many pages are displayed before and after the currently selected page.

<Pagination
  currentPage={this.state.currentPage}
  totalPages={this._getPageCount()}
  onChange={(page) => this._getPage(page)}
  limiter={1} />

Hide first and last page jump instance

Another possible UI customization is the ability to hide the page jumper. These are the buttons at the start or at the end of the control.

It’s possible to hide only one or both buttons, by default those are both shown.

To specify the values it’s possible to use either the hideFirstPageJump or the hideLastPageJump properties.

<Pagination
  currentPage={this.state.currentPage}
  totalPages={this._getPageCount()}
  onChange={(page) => this._getPage(page)}
  hideFirstPageJump={true}
  hideLastPageJump={true} />

Limiter icon instance

The limiter icon is the button displayed to let the user skip all the currently shown pages. It allows navigation to the next (or previous) set of pages. By default the icon used is the Fluent UI’s More one, but it’s possible to specify another one. Remember that this icon will be used both for navigating backward and forward.

In the sample I’ve set the icon to the CirclePlus one.

<Pagination
  currentPage={this.state.currentPage}
  totalPages={this._getPageCount()}
  onChange={(page) => this._getPage(page)}
  limiterIcon={"CirclePlus"} />

Conclusions

The Pagination control is very handy when it comes to have a pagination for your data. It’s an out of the box ready to use pagination. The only things that us developer have to do are setting the current page, the total number of available pages, and handling the onChange event.

Hope this helps!