Paging 3

Why Paging?

Loading an entire dataset into memory wastes RAM and causes slow list scrolling. Paging loads data in pages as the user scrolls, keeping memory usage constant regardless of dataset size.

PagingSource

PagingSource defines how to load pages of data. Each page load returns a LoadResult:

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

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Article> {
        val page = params.key ?: 1
        return try {
            val response = api.getArticles(page = page, pageSize = params.loadSize)
            LoadResult.Page(
                data = response.articles,
                prevKey = if (page == 1) null else page - 1,
                nextKey = if (response.articles.isEmpty()) null else page + 1
            )
        } catch (e: Exception) {
            LoadResult.Error(e)
        }
    }

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

Key points:

• params.key is the page number (or cursor). Start with null for the first page.
• params.loadSize is the number of items to request.
• Return prevKey = null for the first page and nextKey = null when no more data exists.
• getRefreshKey determines where to resume when the user scrolls back to the top.

Pager Configuration

val articlesPager = Pager(
    config = PagingConfig(
        pageSize = 20,
        prefetchDistance = 10,
        enablePlaceholders = false,
        initialLoadSize = 40
    ),
    pagingSourceFactory = { ArticlePagingSource(api) }
).flow

• pageSize: items per page request
• prefetchDistance: how many items before the end to trigger loading
• enablePlaceholders: show empty slots for known-size lists
• initialLoadSize: items in the first load (typically 2x pageSize)

Database-Backed Paging

For offline-first apps, use RoomPagingSource:

@Dao
interface ArticleDao {
    @Query("SELECT * FROM articles ORDER BY publishedAt DESC")
    fun getArticlesPaged(): PagingSource<Int, Article>
}

val dbArticlesPager = Pager(
    config = PagingConfig(pageSize = 20, prefetchDistance = 10),
    pagingSourceFactory = { articleDao.getArticlesPaged() }
).flow

Room returns a PagingSource directly, and the Paging library handles invalidation when data changes.

collectAsLazyPagingItems

In Compose, collect paged data as lazy items:

@Composable
fun ArticleListScreen(viewModel: ArticleViewModel = hiltViewModel()) {
    val articles = viewModel.articlesPager.collectAsLazyPagingItems()

    LazyColumn {
        items(
            count = articles.itemCount,
            key = articles.itemKey { it.id }
        ) { index ->
            val article = articles[index]
            article?.let { ArticleCard(article = it) }
        }

        // Loading indicator at the end
        when (articles.loadState.append) {
            is LoadState.Loading -> {
                item { LoadingIndicator() }
            }
            is LoadState.Error -> {
                item { ErrorMessage(onRetry = { articles.retry() }) }
            }
            is LoadState.NotLoading -> {}
        }
    }
}

Load States

Paging 3 exposes three load states:

• loadState.refresh: initial load or full refresh
• loadState.append: loading the next page
• loadState.prepend: loading the previous page (rare)

Each state is one of: Loading, NotLoading(endOfPaginationReached), or Error(throwable).

Loading and Error UI

@Composable
fun ArticleListScreen(viewModel: ArticleViewModel = hiltViewModel()) {
    val articles = viewModel.articlesPager.collectAsLazyPagingItems()

    when (articles.loadState.refresh) {
        is LoadState.Loading -> {
            CircularProgressIndicator(modifier = Modifier.fillMaxSize())
        }
        is LoadState.Error -> {
            ErrorMessage(
                message = (articles.loadState.refresh as LoadState.Error).error.localizedMessage ?: "Error",
                onRetry = { articles.retry() }
            )
        }
        is LoadState.NotLoading -> {
            LazyColumn {
                items(count = articles.itemCount) { index ->
                    articles[index]?.let { ArticleCard(article = it) }
                }
            }
        }
    }
}

Invalidating the Pager

When the underlying data changes (e.g., new articles available), invalidate the PagingSource:

class ArticleViewModel(private val api: ArticleApi) : ViewModel() {
    val articlesPager = Pager(
        config = PagingConfig(pageSize = 20),
        pagingSourceFactory = { ArticlePagingSource(api) }
    ).flow.cachedIn(viewModelScope)

    fun refresh() {
        articlesPager.invalidate()
    }
}

cachedIn(viewModelScope) caches the Pager output in the ViewModel's scope, so multiple collectors share the same data.