Android Paging Library Tutorial using Retrofit

Hi folks, after android Jetpack we have many new things to learn. So here is Android Paging Library Tutorial for you. Android Paging Library is an important component of Android Jetpack.

Update: Jetpack Paging 3.0 has been released, check the updated Jetpack Paging 3.0 Tutorial.

Many app displays a large set of data to the users, for example consider the Amazon App, it shows you the list of products, and the app has too many products, but it do not loads all the product at once, it shows you some products, as soon as you reaches the last item of the product list it loads more products. This is called paging. 

Android Paging Library Tutorial – Video

If you don’t like reading text and want a visual experience, then here is a complete step by step video series for understanding Android Paging Library.

Why use Paging?

Assume you have more than 1000 items for your list that you are fetching from a backend server. Here are the cons if you are fetching everything at once.

Disadvantages of not using Paging

  • User do not see all the items at once, but you are fetching everything at once, so it will consume more bandwidth uselessly.
  • Creating a large List at once uses more system resources resulting in a lagging app and bad user experience.

Advantages of using Paging

  • You will only load a small chunk from your large data set, it will consume less bandwidth.
  • The app will use less resources resulting in a smooth app and nice user experience.

Android Paging Library

Android paging library is a component of android jetpack. Remember it is not available by default so we need to add it. It helps us to load data gradually and gracefully in our application’s RecyclerView.

In this Android Paging Library Tutorial I will not tell you about the theoretical things about the library. Because to know this thing you can visit the official documentation. Instead of discussing the theoretical bla bla bla we will learn implementing the library in our application, as the official documentation might confuse you.


Before moving ahead, you should go through these tutorials first, as we are going to use these things.

  • Using Retrofit in Android: Complete Retrofit Playlist from Scratch.
    We will use the Retrofit Library to fetch the data from backend API. The above tutorial discusses about Retrofit and Building API from scratch. So you can check the sereis.
  • RecyclerView: RecyclerView Tutorial.
    We will load the items in a RecyclerView after fetching it from server.
  • Android ViewModel: Android ViewModel Tutorial.
    This is another component from Android Jetpack. It helps us to store UI related data in a more efficient way.

Backend API

The important thing is the Backend API. Though you can also load data from SQLite database using Paging Library, but often the app needs to fetch data from our Backend API. You can go through this complete retrofit tutorial series to learn building an API using PHP and MySQL.

In this tutorial we will not build our own API, but I am going to use a readymade API of StackOverflow. Below is the API link.

In the above API URL we are passing the below parameters.

page: The number of page that we want to fetch.
pagesize: The total number of items that we want in the page.
site: The site from which we want to fetch the data.

The above URL will give the following response. 

android paging library tutorial
Android Paging Library Tutorial

The data is coming from StackOverflow, and it has a very very large data set, so you will get may be infinite number of pages.

Now our task is to fetch from the page 1 and load the next page as soon as the user reaches the end of the list. And to do this we will use the Android Paging Library.

Android Paging Library Tutorial

Now let’s get into the real code friends.

Creating a new project

  • As always we will create a new Android Studio project. I have created an Android Project named Paging Library Tutorial.
  • Now before moving ahead we will add the required dependencies.

Adding Dependencies

  • Go to app level build.gradle file and add the following dependencies.

  • After adding all the above required dependencies sync your project and you are good to go. Here we have added a lot of dependencies these are:
    Retrofit and Gson: For fetching and parsing JSON from URL.
    ViewModel: Android architecture component for storing data.
    Paging: The paging library.
    RecyclerView and CardView: For building the List.
    Glide: For loading image from URL.

Creating Model Class

Now we will create a model class in our project. We need this class to parse the JSON response automatically. We have a really complex nested JSON in the response. So we need many classes to bind the response into respective java class automatically.

  • Create a file named and write the following code in it.

  • The above code is pretty simple, I am not using getters and setters just to make it concise and small. The variable names are matching with the JSON keys so the Gson will map the data accordingly.
  • The above file have only one public class (and actually we can have only one public class in a file). The class named StackApiResponse contains the following json.
Android Paging Library Tutorial
Android Paging Library Tutorial
  • Inside the class we are mapping the above JSON object, that is why we have only 4 properties inside StackApiResponse.
  • Then first item inside StackApiResponse is items which contains an array of items, that is why I have a List<Item>, then has_more is boolean and quota_max and quota_remaining.
  • Now inside item we have the following JSON.
Android Paging Library Tutorial 1
Android Paging Library Tutorial
  • Inside item we have another object named owner, that is why I have created another class named Owner, and I have declared an object of type Owner inside the Item class. I hope you got how we define model class for the specified JSON.

Creating Retrofit Singleton Class

  • Each time when we want to fetch data from a new page, we need the Retrofit object. So creating a singleton instance of Retrofit is a good idea.
  • For the singleton instance I will create a new class named RetrofitClient.

  • The above code is pretty simple, if you are having trouble understanding it, then you should first follow the Retrofit Tutorial.

Creating API

  • Now we will create the API call interface.
  • Create an interface named Api and write the following code.

Creating RecyclerView

As I already told you that, we will display the list in the RecyclerView. So let’s build the RecyclerView.

  • Come inside activity_main.xml and define your RecyclerView here.

  • Now for the RecyclerView create one more layout resource file named recyclerview_users.xml and write the following xml code.

Creating PagedListAdapter

We need to fetch the data page wise, so this time we will not use the RecyclerView.Adapter but we will use a PagedListAdapter.

What is PagedListAdapter?

It is a class that has the common behaviours needed for a PagedList for example Item Counting, Page CallBack etc. And don’t get too much confused, the only point here is that this is going to be the adapter for our RecyclerView. 

  • Create a class named ItemAdapter and write the following code.

  • The adapter is almost same as RecyclerView.Adapter<>, the only change here is we have a DIFF_CALLBACK implementation that we are passing to the super(). This callback is used to differentiate two items in a List.
  • For the PagedListAdapter<> we define the Item and the ViewHolder. Item is the item that you want to display, and we already have a class named Item that contains the data that we need to display.

Creating Item Data Source

Now here comes the very important thing, the data source of our item from where we will fetch the actual data. And you know that we are using the StackOverflow API.

For creating a Data Source we have many options, like ItemKeyedDataSource, PageKeyedDataSource, PositionalDataSource. For this example we are going to use PageKeyedDataSource, as in our API we need to pass the page number for each page that we want to fetch. So here the page number becomes the Key of our page.

  • Create a class named ItemDataSource and write the following code.

You might find the above code a little tricky, but it is the most important part of our project. So let’s try to understand it.

  • We extended PageKeyedDataSource<Integer, Item> in the above class. Integer here defines the page key, which is in our case a number or an integer. Every time we want a new page from the API we need to pass the page number that we want which is an integer. Item is the item that we will get from the API or that we want to get. We already have a class named Item.
  • Then we defined the size of a page which is 50, the initial page number which is 1 and the sitename from where we want to fetch the data. You are free to change these values if you want.
  • Then we have 3 overridden methods.
    • loadInitials(): This method will load the initial data. Or you can say it will be called once to load the initial data, or first page according to this example.
    • loadBefore(): This method will load the previous page.
    • loadAfter(): This method will load the next page.

Creating Item Data Source Factory

We are going to use MutableLiveData<> to store our PageKeyedDataSource and for this we need a DataSource.Factory.

Creating ViewModel

  • Now create a class named ItemViewModel and write the following code.

Now before moving ahead rebuild your project. 

Displaying the Paged List

  • Finally come inside and write the following code.

  • Now you are done and you can try running your application.
  • If everything is fine you will see the below output.

  • As you can see it is working fine, and we have a smooth and huge list in our application.

Note: If you are not seeing any item, make sure the API URL is working correctly, by opening the URL in your browser, as sometimes stackoverflow blocks the continuous requests to their URLs. 

Android Paging Library Tutorial Source Code

This tutorial is very big, and little complicated. So you have to follow all the steps carefully. But for some reason if you are not able to make it you can try with my source code as well.

From the below link you can download my source code on GitHub.

git hub repository
Get the Source Code

So that is all for this Android Paging Library Tutorial friends. I hope you found it helpful, so for a payback (just kidding) please share this tutorial with your friends learning android. And for any question feel free to comment. Thank You 🙂

40 thoughts on “Android Paging Library Tutorial using Retrofit”

  1. Hum Firebase database se v paging kar sakte hai kya?? Qki mai apne app mei firebase realtime database hi use kar rha hoon or mujhe v paging implement karna hai, plz help

  2. Very awesome. What if the user connection us halted while scrolling, how can you show a message that data cant be loaded, or a loading progress when we load new page

  3. Let me know how can I send value(i.e parameters) to API which stored in Shared preferences(it needs context)

    I need to send access token which is stored in shared preferences

    Also let me know how to display no data available toast after hasMore value is false, (Toast needs context)

    How can I pass context to ItemDataSource.class ?

  4. Hello dear bellal khan. I am Mohamad from Iran.
    I wanna ask what can I do if I want a pass a @Path or @Field paramater in addition of @Query with retrofit request in DataSource class?


    • Hi Mohamad, in case you want 1to make a Retrofit request with a specific path you would have to do something like this:

      Call getResponse(@Path(“my_path”) String path );

      In case it is a field you want to pass it’s even easier, let’s suppose it is a list of items you want to pass

      Call getResponse(@Field(“item_list”) List list );

  5. Best tutorial for Paging + Retrofit!
    Just a side note: like the previous comment, I need to pass the context to the data source factory, for retrieving the access token from the shared preferences. How can i possibly do that?

  6. Thanks for this simplified explanation. I have implemented this successfully.
    But my LoadBefore function in DataSource is never being called.

    //this will load the previous page
    public void loadBefore(@NonNull final LoadParams params, @NonNull final LoadCallback callback) {

    Other functions are working successfully. loadAfter function is working fine as per the page size. Facing issue only with LoadBefore function

  7. Hello Sir, Really Awesome , but how to implement a progressbar and reload button if i am using this in a fragment. Unable to find any solution.

  8. Nice tutorial!

    Any idea how we can insert native ads efficiently while using this paging library. I mean since vase data is being loaded in chunks, native ads will also have to be added according to the size of this chunk. I just can’t figure out how to do that efficiently.

    Any help would be a great help.


  9. Thanx for the tutorial. I’m a big fan of your page.
    Is it possible to change URL dynamically from mainactivity(i.e user actions) in this project..?
    Can we add filtering and sorting options w.r.t user choice in this project??
    Waiting for a positive response…
    Thank you

  10. showing a white blank screen

    if i hit url on browser then this error occur
    {“error_id”:400,”error_message”:”site is required”,”error_name”:”bad_parameter”}

  11. I got data ItemDataSource but in my activity it gives me zero length list, I’m just mapping this example to my project , not exactly copy and paste the code.

    In my activity onDataChange() call first then it call loadInitial,

  12. Hello,
    Thanks for the tutorial.
    According to my understanding if we are passing number of pages in the api call. We can do it without paging library too as per my understanding we can do it by on page scroll or respective method on scroll we can call api. And is it possible without passing number of items to be displayed. Like we receive full data first and it gets stored in the model then it gets displayed as soon we scroll. As making api calls again and again is efficient way.?

    • Yes obviously it is efficient. Imagine you have more than 100,000 items in your database. Fetching them all at once with a single api call is the worse thing you can do. If you don’t trust me, try Fetching this amount of data and you will understand.

  13. Hello;
    Thanks for the tutorial.
    Could you tell why you need to FIRST_PAGE + 1 in loadInitial method. I try to keep FIRST_PAGE.It has nothing changed.
    , and when i saw data loaded on UI, it was duplicate.

  14. itemPagedList = LivePagedListBuilder(merchentDataSourcefactor!!, pagedListConfig)
    Log.e(“itemPagedList”, “__________________________________” + itemPagedList?.value)

    why display null value sir


Leave a Comment