lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

Paging library UI components and considerations

This guide builds upon the Paging Library overview, describing how you can present lists of information to users in your app's UI, particularly when this information changes.

Connect your UI to your view model

You can connect an instance of LiveData<PagedList> to a PagedListAdapter, as shown in the following code snippet:

private val adapter = ConcertPagedListAdapter()
private lateinit var viewModel: ConcertViewModel

override fun onCreate(savedInstanceState: Bundle?) {
    viewModel = ViewModelProviders.of(this)
            .get(ConcertViewModel::class.java)
    viewModel.concerts.observe(this, adapter::submitList)
}

As data sources provide new instances of PagedList, the activity sends these objects to the adapter. The PagedListAdapter implementation defines how updates are computed, and it automatically handles paging and list diffing. Therefore, your ViewHolder only needs to bind to a particular provided item:

class ConcertPagedListAdapter() : PagedListAdapter<Concert, ConcertViewHolder>(
        object : DiffUtil.ItemCallback<Concert>() {
    // The ID property identifies when items are the same.
    override fun areItemsTheSame(oldItem: Concert, newItem: Concert)
            = oldItem.id = newItem.id

    // Use the "==" operator (or Object.equals() in Java-based code) to know
    // when an item's content changes. Implement equals(), or write custom
    // data comparison logic here.
    override fun areContentsTheSame(oldItem: Concert, newItem: Concert) =
            oldItem.name == newItem.name && oldItem.date == newItem.date
    }
) {
    override fun onBindViewHolder(holder: ConcertViewHolder, position: Int) {
        val concert: Concert? = getItem(position)

        // Note that "concert" is a placeholder if it's null
        holder.bind(concert)
    }
}

The PagedListAdapter handles page load events using a PagedList.Callback object. As the user scrolls, the PagedListAdapter calls PagedList.loadAround() to provide hints to the underlying PagedList as to which items it should fetch from the DataSource.

Implement the diffing callback

The preceding sample shows a manual implementation of areContentsTheSame(), which compares relevant object fields. You can also compare contents using the Object.equals() method in Java-based code or the == operator in Kotlin-based code, but make sure you either implement the equals() method for the object that you're comparing or use a Kotlin-based data class.

Diffing using a different adapter type

If you choose not to inherit from PagedListAdapter—such as when you're using a library that provides its own adapter—you can still use the Paging Library adapter's diffing functionality by working directly with an AsyncPagedListDiffer object.

Provide placeholders in your UI

In cases where you want your UI to display a list before your app has finished fetching data, you can show placeholder list items to your users. The RecyclerView handles this case by setting the list item itself to null temporarily.

Placeholders have the following benefits:

  • Support for scrollbars: The PagedList provides the number of list items to the PagedListAdapter. This information allows the adapter to draw a scrollbar that conveys the full size of the list. As new pages load, the scrollbar doesn't jump because your list doesn't change size.
  • No loading spinner necessary: Because the list size is already known, there's no need to alert users that more items are loading. The placeholders themselves convey that information.

Before adding support for placeholders, though, keep the following preconditions in mind:

  • Requires a countable data set: Instances of DataSource from the Room persistence library can efficiently count their items. If you're using a custom local storage solution or a network-only data architecture, however, it might be expensive or even impossible to determine how many items comprise your data set.
  • Requires adapter to account for unloaded items: The adapter or presentation mechanism that you use to prepare the list for inflation needs to handle null list items. For example, when binding data to a ViewHolder, you need to provide default values to represent unloaded data.
  • Requires same size item views size: If list item sizes can change based on their content, such as social networking updates, crossfading between items doesn't look good. We strongly suggest disabling placeholders in this case.