Paging 3 for Kotlin: Complete Guide with Examples

1. What It Is and Why You Need It

Paging 3 is a library from Google for Android, written in Kotlin, that solves one of the most common tasks in mobile development: paginated data loading (pagination). When you have a list of thousands or millions of items (e.g., a news feed, chat messages, catalog products), loading them all at once is impossible — it would lead to memory overflow, UI freezing, and huge data usage. Paging 3 automates the process of loading data in portions (pages) as the user scrolls through the list.

The library is built on modern principles: it uses Kotlin coroutines for asynchronous work, Flow for reactive data updates, and fully integrates with Jetpack Compose and RecyclerView. Unlike previous versions (Paging 2), Paging 3 offers a cleaner architecture, less boilerplate, and built-in support for error handling, data updates, and caching.

The main value of Paging 3 is that you write the logic for loading a single page (e.g., an API request), and the library itself decides when to request the next one, how to store data in memory, how to notify the adapter about changes, and how to handle loading states (loading, error, empty list). This saves hours of development and makes the application stable even when working with huge datasets.

2. Installation

Paging 3 is a library for Android/Kotlin, so it is installed via the Gradle build system, not via pip or npm. Add the dependency to the build.gradle.kts file (app module):

// build.gradle.kts (Module: app)\ndependencies {\n    // Main Paging 3 library\n    implementation("androidx.paging:paging-runtime-ktx:3.3.5")\n    \n    // If using Jetpack Compose (optional)\n    implementation("androidx.paging:paging-compose:3.3.5")\n    \n    // If using RxJava (optional)\n    implementation("androidx.paging:paging-rxjava3:3.3.5")\n    \n    // For testing (optional)\n    testImplementation("androidx.paging:paging-common:3.3.5")\n}\n

After syncing Gradle, the library is ready to use. The minimum SDK version is 21 (Android 5.0).

3. Quick Start — Minimal Working Example

Let's create a simple screen that loads a list of numbers from 1 to 1000, 20 items per page. The example consists of three parts: data source (PagingSource), ViewModel, and UI (RecyclerView).

Step 1. PagingSource — Data Source

class NumberPagingSource : PagingSource<Int, Int>() {\n    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Int> {\n        return try {\n            // Determine the next page key (if null — first load)\n            val currentPage = params.key ?: 0\n            val pageSize = params.loadSize  // usually 20\n            \n            // Generate data for the current page\n            val start = currentPage * pageSize\n            val end = minOf(start + pageSize, 1000)\n            val numbers = (start until end).toList()\n            \n            // Return the result with keys for the next and previous page\n            LoadResult.Page(\n                data = numbers,\n                prevKey = if (currentPage > 0) currentPage - 1 else null,\n                nextKey = if (end < 1000) currentPage + 1 else null\n            )\n        } catch (e: Exception) {\n            LoadResult.Error(e)\n        }\n    }\n    \n    // Returns the key for refresh (usually null or the first key)\n    override fun getRefreshKey(state: PagingState<Int, Int>): Int? = null\n}\n

Step 2. ViewModel

class MainViewModel : ViewModel() {\n    val pager = Pager