lightbulb_outline Please take our October 2018 developer survey. 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:

Kotlin

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

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

Java

public class ConcertActivity extends AppCompatActivity {
    private ConcertAdapter mAdapter;
    private ConcertViewModel mViewModel;

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mViewModel = ViewModelProviders.of(this).get(ConcertViewModel.class);
        mViewModel.concertList.observe(this, mAdapter::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:

Kotlin

class ConcertAdapter() :
        PagedListAdapter<Concert, ConcertViewHolder>(DIFF_CALLBACK) {
    override fun onBindViewHolder(holder: ConcertViewHolder, position: Int) {
        val concert: Concert? = getItem(position)

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

    companion object {
        private val DIFF_CALLBACK = 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 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 == newItem
        }
    }
}

Java

public class ConcertAdapter
        extends PagedListAdapter<Concert, ConcertViewHolder> {
    protected ConcertAdapter() {
        super(DIFF_CALLBACK);
    }

    @Override
    public void onBindViewHolder(@NonNull ConcertViewHolder holder,
            int position) {
        Concert concert = getItem(position);

        // Note that "concert" can be null if it's a placeholder.
        holder.bindTo(concert);
    }

    private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK =
            new DiffUtil.ItemCallback<Concert>() {
        // The ID property identifies when items are the same.
        @Override
        public boolean areItemsTheSame(Concert oldItem, Concert newItem) {
            return oldItem.getId() == newItem.getId();
        }

        // Use Object.equals() to know when an item's content changes.
        // Implement equals(), or write custom data comparison logic here.
        @Override
        public boolean areContentsTheSame(Concert oldItem, Concert newItem) {
            return oldItem.equals(newItem);
        }
    };
}

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.

Provide feedback

Share your feedback and ideas with us through these resources:

Issue tracker
Report issues so we can fix bugs.
G+ community
Provide feedback and discuss ideas with other developers.

Additional resources

To learn more about the Paging Library, see the following guides and videos: