Building custom pagination component with Angular
Tags: angular, pagination, tutorial, webdev
Published: 2024-05-08 22:34:46

Pagination is undoubtedly one of the most popular approaches to dozed content representation. And it’s absolutely fine to use some out-of-the-box solutions for it if your application uses some library like [NgBootstrap](https://ng-bootstrap.github.io/#/components/pagination/overview) or [Material UI](https://material.angular.io/components/paginator/overview) all round and the designs and functionality they provide is satisfactory to you.
But once you bump into the need of re-styling or customisation of it you usually may choose the way of creating a wrapping component which uses this out-of-the-box component inside and re-define its behaviour or styles by breaking original component encapsulation.
This is a legit approach of course if there are few changes to make. But when you start modifying it over and over trying to satisfy some special customer needs there may be a point when you say: “Come on! It would be easier and faster to create it from scratch than to do all these customisations!”
And you will be absolutely right here! Let’s explore together the way how to implement it in your Angular app.

Impatient readers can find the whole project [here](https://stackblitz.com/edit/angular-ivy-t8kaef). The rest are welcome to follow with me step by step.

---

I like to think about pagination as about select control: we have the list of options (pages) and select one of them. And this is the reason to implement it as a form control. And speaking in terms of Angular it means that we want to implement `ControlValueAccessor` interface. There is an official documentation and a lot of other instructions and descriptions how to implement it. So, we’re not going to dwell on it and only will deal with pagination specific of it.

Of course you may say that we could make this component without implementing ControlValueAccessor interface just using `@Output` property for handling page change events. This point of view is absolutely reasonable and furthermore we’ll have this version of our component here at first as well. But the benefit of implementing ControlValueAccessor is that it gives us more flexibility: we can use or pagination component either as a template form with one- or two-way data binding `([(ngModel)]` or `[ngModel]`+ `(ngModelChange)`) or as a reactive form control (`[formControl]`).

The reactive approach can be very handy when our pagination is supposed to be used in combination with other form controls. For example, we may have a table component which offers user a possibility to sort and filter data by columns, use pagination and table lookup. In this case we can use **RxJS** `combineLatest` method to subscribe and listen to the changes of all these controls only once:

```
combineLates([
  this.searchControl.pipe(
    startWith(this.searchControl.value),
    debounceTime(500)
  ),
  this.filterControl.pipe(startWith(this.filterControl.value)),  
  this.sortControl.pipe(startWith(this.sortControl.value)),
  this.pageControl.pipe(
    startWith(this.pageControl.value),
    debounceTime(500)
  )
]).subscribe((search, filter, sort, pagination) => {
  this.sendRequest({
    search,
    filter,
    sortBy: sort.sortBy,
    sortDirection: sort.sortDirection,
    page: pagination.page,
    pageSize: pagination.pageSize
  };
})
```

As we you can see above with this approach we have to pipe `startWith` to each control, otherwise our subscription won’t start until each control emits at leas one value. In this example we use the initial form values to start with.

Another advantage of reactive approach is the possibility to use `debounceTime` to particular controls which allows us to avoid triggering requests on each key stroke in search input or on each click on pagination **Previous** / **Next** button.

---

So, let’s finally start with pagination itself!

At the first step for the visualising purpose we create a simple array of 100 elements which we’ll paginate later:

```
// app.component.html

<div class="items-wrapper">
  <my-card
    *ngFor="let item of visibleItems.items"
    [item]="item">
  </my-card>
</div>


// app.component.ts

export interface PaginatedResponse<T> {
  items: T[];
  total: number;
}

...

public pageSize = 10;

private readonly items = Array.from(
  Array(100).keys(),
  (item) => item + 1
);

public visibleItems: PaginatedResponse<number> = {
  items: this.items.slice(0, this.pageSize),
  total: this.items.length,
};
```

As a rule the backend sends us a paginated response, which have at least 2 properties:

- `items` — array of items for the particular (requested) page
- `total` — how many matching items they have in the whole.

We’re going to follow this structure in our example even though we don’t have any backend in this example. We’ll just be slicing needed range of the initial array imitating backend responses.

---

On the second step we create a simple pagination component which would allow us to navigate to the first, previous, next, last and particular page from the visible range with no interactions with parent component.

I’m saying _visible range_ because we may have our content split into dozens or hundreds of pages, and we definitely don’t want to show all of them to the user. So we provide `visibleRangeLength` property to limit the visible pages count.

```
// pagination.component.html

<div class="pagination">
  <button
    [disabled]="value === 1"
    (click)="selectPage(1)">
    <<
  </button>
  <button
    [disabled]="value === 1"
    (click)="selectPage(value - 1)">
    <
  </button>
  <button
    *ngFor="let page of visiblePages"
    [ngClass]="value === page && 'selected'"
    (click)="selectPage(page)">
    {{ page }}
  </button>
  <button
    [disabled]="value === totalPages
    (click)="selectPage(value + 1)">
    >
  </button>
  <button
    [disabled]="value === totalPages"
    (click)="selectPage(totalPages)>
    >>
  </button>
</div>


// pagination.component.ts

public value = 1;
public totalPages = 10;
public visibleRangeLength = 5;
public visiblePages: number[];

ngOnInit(): void {
  this.updateVisiblePages();
}

public selectPage(page: number): void {
  this.value = page;
  this.updateVisiblePages();
}

private updateVisiblePages(): void {
  const length = Math.min(this.totalPages, this.visibleRangeLength);
  const startIndex = Math.max(
    Math.min(
      this.value - Math.ceil(length / 2),
      this.totalPages - length
    ),
    0
  );
  this.visiblePages = Array.from(
    new Array(length).keys(),
    (item) => item + startIndex + 1
  );
}
```

The only tricky part here I guess is `updateVisiblePages` method. The main points of it are the following:

- we always want to have visible as many pages as we set in `visibleRangeLength` property
- if `visibleRangeLength` turns out to be bigger than `totalPages` count (and this is absolutely possible as we never know how many pages the backend has for us, especially if we request filtered results) we want to display `totalPages` count
- the selected page should be in the middle of the visible range if possible

Now this component is already functional but it can’t interact with external environment. To turn our component into useable configurable solution we need to:

- convert `value`, `totalPages`, `visibleRangeLength` into component inputs
- to add component output `valueChange` and extend `selectPage` method with the line `this.valueChange.emit(this.value)`

Though we can refactor it a little bit. As we have said previously we usually don't get `totalPages` value from the backend, but we do get total items quantity and then we calculate the `totalPages` on our side depending on the page size. So, instead of having this logic in the **AppComponent** let’s put it in the **PaginationComponent**:

- convert `totalPages` back into the regular public property
- provide input properties `total` (for the total items count) and `pageSize`
- add re-calculation of the `totalPages` value each time our `total` or `pageSize` change

After finishing it our component looks like this:

```
// pagination.component.ts

@Input() value = 1;
@Input() total = 10;
@Input() pageSize = 10;
@Input() visibleRangeLength = 5;
@Output() valueChange = new EventEmitter<number>();

public totalPages: number;
public visiblePages: number[];

ngOnInit(): void {
  this.updateVisiblePages();
}

ngOnChanges(changes: SimpleChanges): void {
  if (changes.total || changes.pageSize) this.updateTotalPages();
}

public selectPage(page: number): void {
  this.value = page;
  this.updateVisiblePages();
  this.valueChange.emit(this.value);
}

private updateVisiblePages(): void {
  const length = Math.min(this.totalPages, this.visibleRangeLength);
  const startIndex = Math.max(
    Math.min(
      this.value - Math.ceil(length / 2),
      this.totalPages - length
    ),
    0
  );
  this.visiblePages = Array.from(
    new Array(length).keys(),
    (item) => item + startIndex + 1
  );
}

private updateTotalPages(): void {
  this.totalPages = Math.ceil(this.total / this.pageSize);
}
```

Now we can apply the pagination to our list of items:

```
// app.component.html

...

<div class="pagination-wrapper">
  <my-pagination
    [total]="visibleItems.total"
    [pageSize]="pageSize"
    (valueChange)="onPageChange($event)">
  </my-pagination>
</div>


// app.component.ts

...

public onPageChange(page: number): void {
  const startIndex = (page - 1) * this.pageSize;
  const items = this.items.slice(
    startIndex,
    startIndex + this.pageSize
  );
  this.visibleItems = { items, total: this.items.length };
}
```

---

On the third step I want to make our component responsible not only for the page but also for the page size selection. So we’ll add the select element to our pagination template and extend and refactor the component logic a bit more.

Obviously, our component should emit page size change event outside. But the business logic may be different here depending on the customer preferences. One may want the page content not to be updated on page size change and only request new data set on page number change. Another may have different thoughts about it.

I personally think that the most transparent way to handle it would be to request the new range of data on the page size change reseting the selected page to 1 in the same time. And this is the approach we’re going to implement further.

At first we’ll extend `value` interface so that it includes two properties `page` and `pageSize`. This will also need to do some refactoring in the existing **PaginationComponent** code (like replacing `value` with `value.page` etc.).

Then we’ll add the following changes:

```
// pagination.component.html

...

<select
  [ngModel]="value.pageSize"
  (ngModelChange)="selectPageSize($event)">
  <option
    *ngFor="let size of pageSizes"
    [value]="size">
    {{ size }}
  </option>
</select>


// pagination.component.ts

...

export interface PaginationValue {
  page: number;
  pageSize: number;
}
...
@Input() value: PaginationValue = { page: 1, pageSize: 5 };
...
@Input() pageSizes: number[] = [5, 10, 25, 50];
@Output() valueChange = new EventEmitter<PaginationValue>();
...
ngOnChanges(changes: SimpleChanges): void {
  if (changes.total || changes.value) this.updateTotalPages();
}

public selectPage(page: number): void {
  this.value = { ...this.value, page };
  ...
}

public selectPageSize(pageSize: string): void {
  this.value = { page: 1, pageSize: +pageSize };
  this.updateTotalPages();
  this.updateVisiblePages();
  this.valueChange.emit(this.value);
}
```

---

And finally let’s turn our component into the `ControlValueAccessor`. For this we only need to remove everything related to the output property `valueChange` and add the following:

```
@Component({
  ...
  providers: [{
    provide: NG_VALUE_ACCESSOR,
    useExisting: forwardRef(() => PaginationComponent),
    multi: true,
  }]
})

export class PaginationComponent implements OnInit, OnChanges, ControlValueAccessor {
  ...
  onChange(value: any) {};
  onTouched() {};

  registerOnChange(fn: any): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: any): void {
    this.onTouched = fn;
  }

  writeValue(value: PaginationValue): void {
    if (!value) return;
    this.value = value;
    this.updateTotalPages();
    this.updateVisiblePages();
  }

  public selectPage(page: number): void {
    ...
    this.onChange(this.value);
  }

  public selectPageSize(pageSize: number): void {
    ...
    this.onChange(this.value);
  }
}
```

And now we can use the pagination as a form control:

```
// app.component.html

...

<my-pagination
  [total]="visibleItems.total"
  [formControl]="paginationControl">
</my-pagination>

<!-- OR  -->

<my-pagination
  [total]="visibleItems.total"
  [ngModel]="pagination"
  (ngModelChange)="onPageChange($event)">
</my-pagination>


// app.component.ts

...

public pagination = { page: 1, pageSize: 10 };

// OR

public readonly paginationControl = new FormControl(this.pagination);

ngOnInit(): void {
  this.paginationControl.valueChanges
    .subscribe(this.onPageChange.bind(this));
}

public onPageChange(pagination: PaginationValue): void {
  const startIndex = (pagination.page - 1) * pagination.pageSize;
  const items = this.items.slice(
    startIndex,
    startIndex + pagination.pageSize
  );
  this.visibleItems = { items, total: this.items.length };
}
```

Thank you for reading it and for your feedbacks!