Skip to content
Tutorials Center
My learning

Topics

Lesson 97 of 104 ยท Projects

Project: News Reader with Paging

Build a news reader with Paging 3 and a RemoteMediator for offline-first lists, Hilt for dependency injection and bottom navigation, with runnable Kotlin stand-ins for each part.

News feeds are endless. A server might hold tens of thousands of articles, and a phone should neither download them all nor show a blank screen when the train goes into a tunnel. This project combines the biggest ideas of the data chapters: paging (load a little at a time as the user scrolls), offline-first (the local database is what the screen reads), dependency injection with Hilt (so the pieces can be wired and replaced), and bottom navigation with several tabs.

You will see the architecture first, then each piece. The real code (Paging 3, Room, Hilt, Compose navigation) is read-only, because the site has no emulator. The TryIts are plain Kotlin stand-ins on Piston: a paginator with a prefetch distance, a RemoteMediator-style loader that writes pages into a fake database, and a small dependency graph with tabs that each keep their own back stack. Review Paging 3, Errors and offline-first, Hilt and Bottom navigation as needed.

What we are building

  • A Feed tab with an endless list of articles, loaded in pages.
  • A Saved tab with bookmarked articles, and a Settings tab.
  • The feed works offline: previously loaded articles are still there, and an error at the bottom offers "Retry".
  • Pull to refresh replaces the cached list with fresh data, but only after the new data has arrived.
  • Each tab keeps its own navigation history when you switch tabs.
flowchart TD
    UI["FeedScreen<br/>LazyColumn of LazyPagingItems"] --> VM["FeedViewModel<br/>Pager flow, cachedIn"]
    VM --> P["Pager"]
    P --> PS["PagingSource<br/>reads Room"]
    P --> RM["RemoteMediator<br/>fetches pages"]
    RM --> API["NewsApi"]
    RM -->|"writes pages and keys"| DB[("Room: articles, remote_keys")]
    PS --> DB
    DB -. "invalidates" .-> PS

The screen only reads from Room through the PagingSource. The RemoteMediator is the only code that talks to the network, and it writes into Room.

Step 1: how paging works

A plain list loads everything into memory. Paging 3 loads a page, shows it, and loads the next page when the user gets close to the end. Three roles matter:

  • A PagingSource knows how to load one page given a key (an offset, a page number or a cursor) and what the next key is.
  • A Pager combines a source with a PagingConfig (page size, how early to load, how many items to keep) and exposes a Flow<PagingData<T>>.
  • The UI collects that flow as LazyPagingItems, and LazyColumn asks for items by index. Reading an item near the end triggers the next load.

The key setting is prefetch distance: how many items before the end of the loaded data the next page should be requested. With a distance of zero, the user hits the end and waits. With a distance of five, loading starts while they still have five articles to read. Also, the first load is bigger than the others, by default three times the page size, so the list fills the screen and there is something to scroll.

The first TryIt is a miniature pager. ArticlePagingSource loads a page by offset and size. SimplePager keeps the items, asks the source for more when an item near the end is shown, and stops when the source says there is no next key. The "user" scrolls through the list one item at a time.

Kotlin A mini pager with a prefetch distance (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The initial load fetched 20 items, then each later page fetched 10, and the last page returned only five items, which told the source there is nothing more. With a prefetch distance of 5 each load starts while five articles are still unread; with 0 it starts only when the last loaded item appears on screen, which on a slow network means a visible pause.

Step 2: the real Paging code

With Room as the source of truth, the PagingSource is generated for you: a DAO query that returns PagingSource<Int, ArticleEntity>. Room invalidates it whenever the table changes, and the pager reloads the visible window from the database.

Kotlin
// read-only: real Room and Paging code
@Entity(tableName = "articles")
data class ArticleEntity(
    @PrimaryKey val id: Long,
    val title: String,
    val summary: String,
    val publishedAt: Long,
)

@Entity(tableName = "remote_keys")
data class RemoteKey(@PrimaryKey val articleId: Long, val nextPage: Int?)

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

    @Upsert suspend fun upsertAll(items: List<ArticleEntity>)
    @Query("DELETE FROM articles") suspend fun clearArticles()
}

@Dao
interface RemoteKeyDao {
    @Upsert suspend fun upsertAll(keys: List<RemoteKey>)
    @Query("SELECT * FROM remote_keys WHERE articleId = :id") suspend fun byArticleId(id: Long): RemoteKey?
    @Query("DELETE FROM remote_keys") suspend fun clear()
}

class FeedRepository @Inject constructor(private val db: AppDatabase, private val api: NewsApi) {
    @OptIn(ExperimentalPagingApi::class)
    fun feed(): Flow<PagingData<Article>> = Pager(
        config = PagingConfig(pageSize = 20, prefetchDistance = 5, enablePlaceholders = false),
        remoteMediator = ArticleRemoteMediator(api, db),
        pagingSourceFactory = { db.articleDao().pagingSource() },
    ).flow.map { data -> data.map { it.toDomain() } }
}

@HiltViewModel
class FeedViewModel @Inject constructor(repo: FeedRepository) : ViewModel() {
    val feed: Flow<PagingData<Article>> = repo.feed().cachedIn(viewModelScope)
}

cachedIn(viewModelScope) keeps the loaded pages in memory across configuration changes and screen visits, so rotating the phone does not reload the list. The UI side:

Kotlin
// read-only: Compose side
@Composable
fun FeedScreen(vm: FeedViewModel = hiltViewModel()) {
    val items = vm.feed.collectAsLazyPagingItems()

    LazyColumn {
        items(count = items.itemCount, key = items.itemKey { it.id }) { index ->
            items[index]?.let { ArticleRow(it) }
        }
        when (val append = items.loadState.append) {
            is LoadState.Loading -> item { CircularProgressIndicator() }
            is LoadState.Error -> item { RetryRow(onRetry = { items.retry() }) }
            else -> Unit
        }
    }
    if (items.loadState.refresh is LoadState.Error && items.itemCount == 0) {
        FullScreenError(onRetry = { items.refresh() })
    }
}

Reading items[index] is what registers the access and triggers prefetching, so avoid copying the whole thing into a list. The key keeps items stable when the list changes under the user's finger.

Step 3: the RemoteMediator

Without a mediator, the Pager would read only from its source and nothing would put data into the database. A RemoteMediator is called when the pager runs out of data (APPEND) or when a refresh is requested (REFRESH). It fetches from the network and writes into Room in one transaction. Because the screen reads Room through the PagingSource, the new rows appear automatically.

The mediator needs to know which page comes next. A common approach is a small table of remote keys: for each article, the next page to load (or null for the last one). Here is the real shape:

Kotlin
// read-only: real mediator
@OptIn(ExperimentalPagingApi::class)
class ArticleRemoteMediator(private val api: NewsApi, private val db: AppDatabase) : RemoteMediator<Int, ArticleEntity>() {

    override suspend fun load(loadType: LoadType, state: PagingState<Int, ArticleEntity>): MediatorResult {
        val page = when (loadType) {
            LoadType.REFRESH -> 1
            LoadType.PREPEND -> return MediatorResult.Success(endOfPaginationReached = true)
            LoadType.APPEND -> {
                val last = state.lastItemOrNull() ?: return MediatorResult.Success(endOfPaginationReached = false)
                val key = db.remoteKeyDao().byArticleId(last.id)
                key?.nextPage ?: return MediatorResult.Success(endOfPaginationReached = true)
            }
        }

        return try {
            val response = api.articles(page = page, pageSize = state.config.pageSize)
            val end = response.articles.isEmpty() || page >= response.totalPages
            db.withTransaction {
                if (loadType == LoadType.REFRESH) {
                    db.remoteKeyDao().clear()
                    db.articleDao().clearArticles()
                }
                db.articleDao().upsertAll(response.articles.map { it.toEntity() })
                db.remoteKeyDao().upsertAll(response.articles.map { RemoteKey(it.id, if (end) null else page + 1) })
            }
            MediatorResult.Success(endOfPaginationReached = end)
        } catch (e: IOException) {
            MediatorResult.Error(e)
        } catch (e: HttpException) {
            MediatorResult.Error(e)
        }
    }
}

Look at the important rules: a refresh clears the table inside the transaction after the response arrived, so an offline refresh leaves the old articles in place. Network failures are returned as MediatorResult.Error, never thrown out of load, so the UI shows a retry row. And APPEND with no remote key means the end was reached.

You can also override initialize() to return InitializeAction.SKIP_INITIAL_REFRESH when the cache is young enough (for example under an hour), so opening the app does not hit the network each time. If the cache is old, return LAUNCH_INITIAL_REFRESH.

The second TryIt is that mediator with a fake network and a fake database. We can switch the network off, change the server's "edition" to see a refresh replace content, and count network calls.

Kotlin A RemoteMediator over a fake database (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Follow the numbered steps. After step 3 the final page has been loaded and the remote keys say "no next page"; step 4 returns Success(true) without touching the network (the call count does not change). In step 5 the failed refresh did not erase the 15 cached articles. In step 6 the refresh replaced all of them with edition 2 content, which also shrank the list back to the first page, exactly like pull-to-refresh in a real feed. In step 7 the append error would show a retry row at the bottom while the articles remain visible.

Step 4: Hilt wires it together

So far many objects need each other: the ViewModel needs the repository, which needs the database and the API, which need a Retrofit client. Hilt generates the code that creates and shares them, and you only describe how to build the pieces.

Kotlin
// read-only: Hilt setup
@HiltAndroidApp
class NewsApp : Application()

@AndroidEntryPoint
class MainActivity : ComponentActivity() { /* setContent { NewsRoot() } */ }

@Module
@InstallIn(SingletonComponent::class)
object DataModule {
    @Provides @Singleton
    fun database(@ApplicationContext context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, "news.db").build()

    @Provides @Singleton
    fun newsApi(): NewsApi = Retrofit.Builder()
        .baseUrl("https://news.example.com/")
        .addConverterFactory(Json { ignoreUnknownKeys = true }.asConverterFactory("application/json".toMediaType()))
        .build()
        .create(NewsApi::class.java)
}

FeedRepository has an @Inject constructor, so Hilt knows how to build it from the two provided objects. @HiltViewModel classes are created by the hiltViewModel() call and scoped to the navigation destination. @Singleton means one instance for the whole app: one database, one API client.

The third TryIt shows the same idea without annotations: an AppGraph that creates each singleton lazily the first time somebody asks for it, and a store that keeps one ViewModel per tab alive. Next to it is the bottom navigation state where each tab owns its own stack.

Kotlin A tiny dependency graph and per-tab back stacks (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output shows laziness and sharing: Network and the repository are each created once, when the first ViewModel asks for them, and the Saved ViewModel receives the very same repository. A ViewModel in the store survives switching tabs. The navigation part shows the behavior users expect from a bottom bar: every tab remembers its own history, and pressing back unwinds the current tab first, then jumps to the start tab, and only then leaves the app. In real Navigation Compose you get this with saveState = true and restoreState = true on the tab navigation, as covered in the bottom navigation lesson.

Putting the navigation together

Kotlin
// read-only: bottom bar and tabs
@Composable
fun NewsRoot() {
    val navController = rememberNavController()
    val backStack by navController.currentBackStackEntryAsState()
    val destination = backStack?.destination

    Scaffold(bottomBar = {
        NavigationBar {
            TopLevel.entries.forEach { tab ->
                NavigationBarItem(
                    selected = destination?.hierarchy?.any { it.hasRoute(tab.route::class) } == true,
                    onClick = {
                        navController.navigate(tab.route) {
                            popUpTo(navController.graph.findStartDestination().id) { saveState = true }
                            launchSingleTop = true
                            restoreState = true
                        }
                    },
                    icon = { Icon(tab.icon, contentDescription = null) },
                    label = { Text(tab.label) },
                )
            }
        }
    }) { padding -> NewsNavHost(navController, Modifier.padding(padding)) }
}

Ideas for extending it

  • Article detail screen with only the article id in the route; the detail reads from Room.
  • Bookmarks: a saved flag column and a second Pager over WHERE saved = 1.
  • Search with a separate PagingSource and a debounced query (collecting flows).
  • Separators: insertSeparators to add date headers such as "Today" between items.
  • Tests: use fake NewsApi and an in-memory Room database, and test the mediator's load directly (Room and instrumented tests).

Common mistakes

  • Reading the network response directly in the UI and using Room only as an afterthought: the list then disappears offline.
  • Clearing the cache before the refresh response arrives, so a failed refresh wipes the screen.
  • Copying LazyPagingItems into a plain list, which defeats paging and triggers loading everything.
  • Forgetting cachedIn(viewModelScope), so every rotation restarts the load.
  • A PagingSource ordering that is not stable, so items jump around when new rows arrive.
  • Putting a @Singleton on something that holds an Activity context.
  • Sharing one back stack between tabs, so switching tabs loses the user's place.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the prefetch distance in PagingConfig control?

    A larger distance starts loading earlier, so the user is less likely to reach the end and wait. A distance of zero loads only when the last item is shown.
  2. 2. In an offline-first Paging setup, who writes network results into Room?

    The RemoteMediator fetches pages when the pager needs more data and stores them in a transaction. The UI only reads from Room through the PagingSource.
  3. 3. Why should a REFRESH clear the old articles only after the network response has arrived?

    If the table were cleared first, an offline refresh would leave the user with nothing. Clearing and inserting inside one transaction after a successful fetch keeps the old data on failure.
  4. 4. What does cachedIn(viewModelScope) do?

    It caches the paged data in the ViewModel's scope, so a recreated screen shows the already loaded pages instead of reloading.
  5. 5. With saveState and restoreState on bottom navigation, what happens when a user returns to a tab?

    Each tab's back stack is saved when you leave it and restored when you come back, which is the behavior users expect from a bottom navigation bar.

Summary

  • Paging 3 loads data in pages: a PagingSource loads one page, a Pager configures it, and LazyPagingItems feeds the LazyColumn; prefetch distance decides how early the next page is requested.
  • For offline-first, Room is the source of truth: the DAO provides the PagingSource, and a RemoteMediator fetches pages and writes articles and remote keys in a transaction.
  • Refresh clears the cache only after new data has arrived; errors become MediatorResult.Error and a retry row, not a crash or a blank screen.
  • cachedIn(viewModelScope) keeps loaded pages across rotation.
  • Hilt builds the object graph: @Provides for the database and API, @Inject constructors, @Singleton for shared instances and @HiltViewModel for ViewModels.
  • Bottom navigation keeps one back stack per tab with saveState and restoreState.
  • The real Paging, Room, Hilt and navigation code is read-only; the TryIts are Kotlin stand-ins for the paginator, the mediator, the graph and the tabs.

Next: Practice: Compose and State Exercises