pagination-patterns

Pagination Patterns for Mobile

Dependencies (Android)

dependencies {
    val pagingVersion = "3.5.1"
    implementation("androidx.paging:paging-compose:$pagingVersion") // brings in paging-common
    implementation("androidx.paging:paging-runtime:$pagingVersion") // only for RecyclerView/PagingDataAdapter
    testImplementation("androidx.paging:paging-testing:$pagingVersion")
}

KMP note: paging-common and paging-testing went multiplatform in 3.3; paging-compose shipped only an Android artifact then and gained the non-Android targets (JVM/desktop, Apple, Linux, MinGW, JS, wasmJs) in 3.4.0. On 3.4+ both Pager/PagingSource and collectAsLazyPagingItems() can live in commonMain; paging-runtime (and the RxJava/Guava artifacts) stay Android-only.

// KMP: commonMain
implementation("androidx.paging:paging-common:3.5.1")
implementation("androidx.paging:paging-compose:3.5.1")
// androidMain, only if you also use RecyclerView/PagingDataAdapter
implementation("androidx.paging:paging-runtime:3.5.1")

Paging 3.5 added append(), prepend(), refresh(), refresh(item) and retry() as members on Pager itself, for driving loads without a UI presenter, plus the Flow<PagingData<T>>.asItemSnapshotListFlow() operator, which converts the stream into a Flow<ItemSnapshotList<T>> that can be combined with other sources, shared by multiple collectors without cachedIn, or exposed as part of UI state.

For deeper Android-specific coverage prefer android-skills:paging.

PagingSource Implementation

class ArticlePagingSource(
    private val api: ArticleApi,
    private val query: String
) : PagingSource<Int, Article>() {

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Article> {
        val page = params.key ?: STARTING_PAGE
        return try {
            val response = api.searchArticles(
                query = query,
                page = page,
                // REFRESH asks for initialLoadSize, APPEND/PREPEND for pageSize
                pageSize = params.loadSize
            )
            LoadResult.Page(
                data = response.articles,
                prevKey = if (page == STARTING_PAGE) null else page - 1,
                // Advance by the number of pages actually consumed. With
                // initialLoadSize > pageSize, a plain `page + 1` re-fetches rows
                // the first load already returned.
                nextKey = if (response.articles.isEmpty()) null
                          else page + (params.loadSize / PAGE_SIZE)
            )
        } catch (e: IOException) {
            LoadResult.Error(e)
        } catch (e: HttpException) { // Retrofit; with Ktor catch ResponseException instead
            LoadResult.Error(e)
        }
    }

    override fun getRefreshKey(state: PagingState<Int, Article>): Int? =
        state.anchorPosition?.let { anchor ->
            val closest = state.closestPageToPosition(anchor)
            closest?.prevKey?.plus(1) ?: closest?.nextKey?.minus(1)
        }

    private companion object {
        const val STARTING_PAGE = 1
        const val PAGE_SIZE = 20 // must equal PagingConfig.pageSize
    }
}