Mastering Pagination in Spring Boot: The Ultimate 2025 Guide

Why Pagination Matters

Paging limits the amount of data sent per API call. Without it, large query results can cause:

• Network strain with huge payloads
• Memory issues in clients or servers
• Slow UI performance and bad UX
• Harder to implement infinite scroll or filtering

Pagination, paired with filtering and sorting, builds scalable, user-friendly APIs.

Basic Pagination with Query Params

The simplest pagination passes page and size parameters in the request. Example controller method:

@GetMapping("/items")
public List<Item> getItems(@RequestParam int page, @RequestParam int size) {
  int start = page * size;
  return itemRepository.findAll()
    .stream()
    .skip(start)
    .limit(size)
    .collect(Collectors.toList());
}
          

While easy, this approach doesn't handle sorting or total counts well.

Pagination Using Spring Data Pageable

Spring Data provides the Pageable interface and Page response for pagination implementation.

@GetMapping("/items")
public Page<Item> getItems(Pageable pageable) {
  return itemRepository.findAll(pageable);
}
          

This supports page, size, sorting params automatically, returns page metadata (total pages, total elements), improving UX.

Custom Pagination Strategies

For complex queries or NoSQL DBs, you might implement keyset pagination or cursor-based pagination to improve performance with very large data.

These techniques use last-seen IDs or timestamps for efficient next-page retrieval without offset skips.

Real GitHub Projects Doing Pagination

Spring Boot Pagination Repository: github.com/spring-projects/spring-data-examples

Sample API with Cursor Pagination: github.com/thombergs/code-examples

Reviewing popular open-source repos shows various approaches and best practices that can be adapted to your needs.

Pagination Best Practices

• Always provide clear metadata (totalPages, totalElements, currentPage)
• Support sorting and filtering along with pagination
• Use cursor/keyset pagination for large data to improve performance
• Validate query parameters and handle out-of-range pages gracefully
• Document API pagination clearly for clients