Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Get Started AndroidX Community

Paging

The Paging Library makes it easier for you to load data gradually and gracefully within your app's RecyclerView. See the reference docs for more information.

Declaring dependencies

To add a dependency on Paging, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
  def paging_version = "2.1.0"

  implementation "androidx.paging:paging-runtime:$paging_version" // For Kotlin use paging-runtime-ktx

  // alternatively - without Android dependencies for testing
  testImplementation "androidx.paging:paging-common:$paging_version" // For Kotlin use paging-common-ktx

  // optional - RxJava support
  implementation "androidx.paging:paging-rxjava2:$paging_version" // For Kotlin use paging-rxjava2-ktx
}

For information on using Kotlin extensions, see ktx documentation.

For more information about dependencies, see Add Build Dependencies.

Version 2.1.0

January 25, 2019

Paging 2.1.0 is released with no changes from 2.1.0-rc01.

Version 2.1.0-rc01

December 6, 2018

Paging 2.1.0-rc01 is released with no changes from 2.1.0-beta01.

Version 2.1.0-beta01

November 1, 2018

Paging 2.1.0-beta01 is released with no changes from 2.1.0-alpha01.

Version 2.1.0-alpha01

October 12, 2018

Paging 2.1.0-alpha01 has two major additions - page dropping, and KTX extension libraries for every artifact - as well as several other API changes and bugfixes.

API Changes

  • Added PagedList.Config.Builder.setMaxSize() for limiting the number of loaded items in memory.
  • Added androidx.paging.Config() as a Kotlin alternative for PagedList.Config.Builder
  • Added androidx.paging.PagedList() as a Kotlin alternative for PagedList.Builder
  • Added DataSourceFactory.toLiveData() as a Kotlin alternative for LivePagedListBuilder
  • Added DataSourceFactory.toObservable() and toFlowable() as Kotlin alternatives for RxPagedListBuilder
  • Added AsyncPagedListDiffer.addPagedListListener() for listening to when PagedList is swapped. b/111698609
  • Added PagedListAdapter.onCurrentListChanged() variant that passes old and new list, deprecated previous variant.
  • Added PagedListAdapter/AsyncPagedListDiffer.submitList() variants which take an additional callback that triggers if/when the pagedlist is displayed, after diffing. This allows you to synchronize a PagedList swap with other UI updates. b/73781068
  • PagedList.getLoadedCount() added to let you know how many items are in memory. Note that the return value is always equal to .size() if placeholders are disabled.

Bug Fixes

  • Fixed a race condition when diffing if lists are reused b/111591017
  • PagedList.loadAround() now throws IndexOutOfBoundsException when index is invalid. Previously it could crash with an unclear other exception.
  • Fixed a case where an extremely small initial load size together with unchanged data would result in no further loading b/113122599

Version 2.0.0

October 1, 2018

Paging 2.0.0 is released with a single bugfix.

Bug Fixes

  • Fixed a crash that could occur with very fast scrolling using PositionalDataSource and placeholders b/114635383.

Version 2.0.0-beta01

July 2, 2018

Bug Fixes

  • Fixed content disappearing in some prepend cases (placeholders disabled, PositionalDataSource) b/80149146
  • (Already released in 1.0.1) Fixed crashes where PagedListAdapter and AsyncPagedListDiffer would fail to signal move events. b/110711937

Pre-AndroidX Dependencies

For the pre-AndroidX versions of Paging that follow, include these dependencies:

dependencies {
    def paging_version = "1.0.0"

    implementation "android.arch.paging:runtime:$paging_version"

    // alternatively - without Android dependencies for testing
    testImplementation "android.arch.paging:common:$paging_version"

    // optional - RxJava support
    implementation "android.arch.paging:rxjava2:$paging_version"
}

Version 1.0.1

June 26, 2018

Paging 1.0.1 is released with a single bugfix in runtime. We highly recommend using 1.0.1 for stability. Paging RxJava2 1.0.1 is also released, and is identical to 1.0.0-rc1.

Bug Fixes

  • Fixed crashes where PagedListAdapter and AsyncPagedListDiffer would fail to signal move events. b/110711937

RxJava2 Version 1.0.0-rc1

May 16, 2018

Paging RxJava2 1.0.0-rc1 is moving to release candidate with no changes from the initial alpha.

Version 1.0.0-rc1

April 19, 2018 Paging Release Candidate

We do not have any more known issues or new features scheduled for the Paging 1.0.0 release. Please upgrade your projects to use 1.0.0-rc1 and help us battle test it so that we can ship a rock solid 1.0.0.

There are no changes in this release, it is the same as 1.0.0-beta1.

Version 1.0.0-beta1

April 5, 2018

Paging will be in beta for a short time before progressing to release candidate. We are not planning further API changes for Paging 1.0, and the bar for any API changes is very high.

Alpha RxJava2 support for Paging is released as a separate optional module (android.arch.paging:rxjava2:1.0.0-alpha1) and will temporarily be versioned separately until it stabilizes.

This new library provides an RxJava2 alternative to LivePagedListBuilder, capable of constructing Observables and Flowables, taking Schedulers instead of Executors:

Kotlin

val pagedItems = RxPagedListBuilder(myDataSource, /* page size */ 50)
        .setFetchScheduler(myNetworkScheduler)
        .buildObservable()

Java

Observable<PagedList<Item>> pagedItems =
        RxPagedListBuilder(myDataSource, /* page size */ 50)
                .setFetchScheduler(myNetworkScheduler)
                .buildObservable();

New Features

  • RxPagedListBuilder is added via the new android.arch.paging:rxjava2 artifact.

API Changes

  • API changes to clarify the role of executors in builders:

    • Renamed setBackgroundThreadExecutor() to setFetchExecutor() (in PagedList.Builder and LivePagedListBuilder)

    • Renamed setMainThreadExecutor() to setNotifyExecutor() (in PagedList.Builder).

  • Fixed PagedList.mCallbacks member to be private.

Bug Fixes

  • LivePagedListBuilder triggers initial PagedList load on the specified executor, instead of the Arch Components IO thread pool.

  • Fixed invalidate behavior in internal DataSource wrappers (used to implement DataSource.map, as well as placeholder-disabled PositionalDataSource loading) b/77237534

Version 1.0.0-alpha7

March 21, 2018

Paging 1.0.0-alpha7 is released alongside Lifecycles 1.1.1. As Paging alpha7 depends on the move of the Function class mentioned above, you will need to update your lifecycle:runtime dependency to android.arch.lifecycle:runtime:1.1.1.

Paging alpha7 is planned to be the final release before Paging hits beta.

API Changes

  • DataSource.LoadParams objects now have a public constructor and DataSource.LoadCallback objects are now abstract. This enables wrapping a DataSource or directly testing a DataSource with a mock callback. b/72600421
  • Mappers for DataSource and DataSource.Factory
    • map(Function<IN,OUT>) allows you to transform, wrap, or decorate results loaded by a DataSource.
    • mapByPage(<List<IN>,List<OUT>>) enables the same for batch processing (e.g. if items loaded from SQL need to additionally query a separate database, that can be done as a batch.)
  • PagedList#getDataSource() is added as a convenience method b/72611341
  • All deprecated classes have been removed from the API, including the remains of recyclerview.extensions package, and the LivePagedListProvider.
  • DataSource.Factory is changed from an interface to an abstract class to enable map functionality.

Bug Fixes

  • Changed Builders to be final. b/70848565
  • Room DataSource implementation is now fixed to handle multi-table queries - this fix is contained within Room 1.1.0-beta1, see above.
  • Fixed a bug where BoundaryCallback.onItemAtEndLoaded would not be invoked for PositionalDataSource if placeholders are enabled and the total size is an exact multiple of the page size.

Version 1.0.0-alpha5

January 22, 2018

Bug Fixes

  • Fix page loading when placeholders are disabled b/70573345
  • Additional logging for tracking down IllegalArgumentException bug b/70360195 (and speculative Room-side fix)
  • Javadoc sample code fixes b/70411933, b/71467637