Paging

The Paging Library makes it easier for you to load data gradually and gracefully within your app's RecyclerView.

Latest Update	Current Stable Release	Next Release Candidate	Beta Release	Alpha Release
October 1, 2020	2.1.2	-	-	3.0.0-alpha07

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.2"

  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.

Alternatively, you can try out the alpha release of Paging 3.0. To use Paging 3.0, add the following dependencies to your build.gradle file instead:

dependencies {
  def paging_version = "3.0.0-alpha07"

  implementation "androidx.paging:paging-runtime:$paging_version"

  // alternatively - without Android dependencies for tests
  testImplementation "androidx.paging:paging-common:$paging_version"

  // optional - RxJava2 support
  implementation "androidx.paging:paging-rxjava2:$paging_version"

  // optional - Guava ListenableFuture support
  implementation "androidx.paging:paging-guava:$paging_version"
}

For more information about dependencies, see Add Build Dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 3.0.0

Version 3.0.0-alpha07

October 1, 2020

androidx.paging:paging-*:3.0.0-alpha07 is released. Version 3.0.0-alpha07 contains these commits.

API Changes

Async PagingData Guava-based operators now accept an Executor as a param, to control execution context. (Id4372)

Bug Fixes

Fixed IndexOutOfBounds exception thrown in RemoteMediator due to a race condition. (I00b7f, b/165821814)
Fixed a race condition in DataSource -> PagingSource conversion that could cause the resulting PagingSource to ignore invalidation signals from DataSource.
Fixed an issue in page fetchin logic that would sometimes cause it to fail to pick up new generations of PagingSource until PagingDataAdapter.refresh() was invoked
Fixed an issue that would cause scroll-position to sometimes be lost when using a DataSource converted into a PagingSource (such as the one produced by Room), in conjunction with RemoteMediator

External Contribution

Thanks to @simonschiller for adding RxJava2, RxJava3, and Guava-based async transformation operators for PagingData!

Version 3.0.0-alpha06

September 2, 2020

androidx.paging:paging-*:3.0.0-alpha06 is released. Version 3.0.0-alpha06 contains these commits.

API Changes

UnsupportedOperationException with clearer messaging around lack of support for stable ids is now thrown whenever PagingDataAdapter.setHasStableIds is called. (Ib3890, b/158801427)

Bug Fixes

insertSeparators no longer filters out empty pages allowing prefetch distance to be respected by the presenter even in cases where many empty pages are inserted. (I9cff6, b/162538908)

Version 3.0.0-alpha05

August 19, 2020

androidx.paging:paging-*:3.0.0-alpha05 is released. Version 3.0.0-alpha05 contains these commits.

Bug Fixes

Paging now correctly prefetches pages even when the presented data is heavily filtered
Returning LoadResult.Error to a retried load no longer causes Item accesses to incorrectly re-trigger retry

External Contribution

Thanks to Clara F for helping clean up some tests! (549612)

Version 3.0.0-alpha04

August 5, 2020

androidx.paging:paging-*:3.0.0-alpha04 is released. Version 3.0.0-alpha04 contains these commits.

API Changes

Added peek() API to AsyncPagingDataDiffer and PagingDataAdapter to allow presented data access without trigger page loads. (I38898, b/159104197)
Added a snapshot() API to PagingDataAdapter and AsyncPagingDataDiffer to allow retrieving the presented items without triggering page fetch. (I566b6, b/159104197)
Added a PagingData.from(List<T>) constructor to allow presenting static lists, which can be combined with the overall PagingData flow to show static lists in certain states, e.g., before initial REFRESH finishes or simply for testing transformations. (Id134d)
Deprecate dataRefresh Flow / Listener APIs as they were intended to expose the presented items state on REFRESH, but with improvements to loadState Flow / Listener callback timing, and itemCount property, it is redundant (Ia19f3)
Added RxJava3 compatibility wrappers for PagingSource and RemoteMediator (I49ef3, b/161480176)

Bug Fixes

PositionalDataSource converted into PagingSource via toPagingSourceFactory helper, including PagingSource generated by Room now correctly mark themselves to support jumping. (I3e84c, b/162161201)
Fixed a bug where using the synchronous variant of submitData would sometimes lead to a race causing a ClosedSendChannelException (I4d702, b/160192222)

External Contribution

Thanks to Zac Sweers for adding RxJava3 compatibility wrappers on behalf of Slack! (I49ef3, b/161480176)

Version 3.0.0-alpha03

July 22, 2020

androidx.paging:paging-*:3.0.0-alpha03 is released. Version 3.0.0-alpha03 contains these commits.

API Changes

The constructor for PagingState is now public, which should make testing implementations of getRefreshKey() easier (I8bf15)
Hid DataSource kotlin map function variants from Java, to resolve ambiguity between original and kotlin variants. (If7b23, b/161150011)
Redundant APIs intended as conveniences for Kotlin users have been marked @JvmSynthetic (I56ae5)
Added overloads for LoadResult.Page's constructor which defaults itemsBefore and itemsAfter to COUNT_UNDEFINED (I47849)
Made existing PagingData operators accept suspending methods and introduced new mapSync, flatMapSync, and filterSync non-suspending operators for Java users. The existing transformation methods have been moved to extension functions so Kotlin users will now need to import them. (I34239, b/159983232)

Bug Fixes

Room (and PositionalDataSource) PagingSources will now display a leading separator as part of the first page, so the user doesn't need to scroll to reveal it. (I6f747, b/160257628)
Item accesses on placeholders now correctly trigger PagingSource loads until a page is returned that fulfills the requested index after being transformed by PagingData.filter() (I95625, b/158763195)
Fix for a bug where sometimes scrolling after PagingSource returns an error could prevent PagingDataAdapter.retry() from retrying. (I1084f, b/160194384)
Fixes an issue where item accesses after dropping a page might not load pages although the item access was within prefetchDistance (Ie95ae, b/160038730)
Setting PagingConfig.maxSize no longer enables placeholders after a drop event (I2be29, b/159667766)

Version 3.0.0-alpha02

June 24, 2020

androidx.paging:paging-*:3.0.0-alpha02 is released. Version 3.0.0-alpha02 contains these commits.

API Changes

Added overloads for PagingConfig's constructor with common default values (I39c50, b/158576040)
Added overloads for constructors of PagingDataAdapter and AsyncPagingDataDiffer with common default values (Ie91f5)
The adapter APIs, dataRefreshFlow and dataRefreshListener now pass a Boolean to signal whether a PagingData is empty (I6e37e, b/159054196)
Added RxJava and Guava APIs for RemoteMediator - RxRemoteMediator and ListenableFutureRemoteMediator
Added helpers to PagingState for common item access such as isEmpty() and firstItemOrNull() (I3b5b6, b/158892717)

Bug Fixes

Pager now checks for PagingSource reuse in factory, to prevent accidental reuse of invalid PagingSources, which gave an unclear error (I99809, b/158486430)
Failures from RemoteMediator REFRESH no longer prevent PagingSource from loading (I38b1b, b/158892717)
The non-suspending version of submitData no longer causes a crash due to concurrent collection on multiple PagingData when called after the suspending version of submitData. (I26358, b/158048877)
Fixed "cannot collect twice from pager" exception that could occur after config change (I58bcc, b/158784811)

Version 3.0.0-alpha01

June 10, 2020

androidx.paging:paging-*:3.0.0-alpha01 is released. Version 3.0.0-alpha01 contains these commits.

The Paging Library has updated to 3.0, to enable several major new features.

New Features of 3.0

First-class support for Kotlin coroutines and Flow.
Support for async loading with coroutines suspend functions, RxJava Single or Guava ListenableFuture primitives.
Built-in load state and error signals for responsive UI design, including retry and refresh functionality.
Improvements to the repository layer
- Simplified data source interface
- Simplified network + database pagination
- Cancellation support
Improvements to the presentation layer

Known Issues

Paging 3 javadocs are not yet available. In the interim, please use the guides linked above or the Kotlin docs. (b/158614050)

Version 2.1.2

March 18, 2020

androidx.paging:paging:2.1.2 is released. Version 2.1.2 contains these commits against 2.1.0.

Bug Fixes

Fix for IndexOutOfBoundsException in rare cases when converting a position during invalidation.

Release issue

Paging version 2.1.1 was released incorrectly from a misconfigured branch, exposing partially-implemented APIs and functionality upcoming in a future release.
Paging 2.1.2 contains the load-centering fix originally released in 2.1.1, but this time correctly cherry-picked atop the 2.1.0 release. It is strongly recommended to upgrade to this release, if you are currently on 2.1.1.

Version 2.1.1

December 18, 2019

androidx.paging:paging-*:2.1.1 is released. Version 2.1.1 contains these commits.

Bug fixes

Contiguous initial loads from PositionalDataSources are now centered around last access when placeholders disabled

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

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

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