Paging
The Paging Library makes it easier
for you to load data gradually and gracefully within your app's
RecyclerView
.
This table lists all the artifacts in the
androidx.paging
group.
Artifact
|
Stable Release
|
Release Candidate
|
Beta Release
|
Alpha Release
|
paging-*
|
3.3.0
|
-
|
-
|
-
|
paging-compose
|
3.3.0
|
-
|
-
|
-
|
This library was last updated on: May 14, 2024
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:
Groovy
dependencies {
def paging_version = "3.3.0"
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 - RxJava3 support
implementation "androidx.paging:paging-rxjava3:$paging_version"
// optional - Guava ListenableFuture support
implementation "androidx.paging:paging-guava:$paging_version"
// optional - Jetpack Compose integration
implementation "androidx.paging:paging-compose:3.3.0"
}
Kotlin
dependencies {
val paging_version = "3.3.0"
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 - RxJava3 support
implementation("androidx.paging:paging-rxjava3:$paging_version")
// optional - Guava ListenableFuture support
implementation("androidx.paging:paging-guava:$paging_version")
// optional - Jetpack Compose integration
implementation("androidx.paging:paging-compose:3.3.0")
}
For information on using Kotlin extensions, see
ktx documentation
.
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.3
Version 3.3.0
May 14, 2024
androidx.paging:paging-*:3.3.0
is released. Version 3.3.0 contains
these commits
.
Important changes since 3.2.0
PagingDataPresenter
is now a public class. Multiplatform presenters can now be built on top of
PagingDataPresenter
rather than requiring internal Paging APIs or
paging-runtime
’s
AsyncPagingDataDiffer
.
- Added new
LoadStates
and
CombinedLoadStates
helper methods in
hasError
and
isIdle
to check if
LoadStates
is in Error or
NotLoading
state, respectively. Also added a new
awaitNotLoading()
Kotlin extension method on
Flow<CombinedLoadStates>
that waits until a load has settled into either
NotLoading
or Error state.
PagingData.empty()
now dispatches
NotLoading
states by default unless custom
LoadStates
are passed to its constructor. This departs from existing behavior where it doesn't dispatch
LoadStates
when submitted to a
PagingDataAdapter
or it dispatches Loading states when collected as
LazyPagingItems
. When collected as
LazyPagingItems
, it will now also display an empty list immediately upon initial composition.
Kotlin Multiplatform Compatibility
Paging now ships artifacts compatible with Kotlin Multiplatform, thanks in large part to upstreamed work from CashApp's
multiplatform-paging
project.
paging-common
has moved all Paging 3 APIs to
common
and is now compatible with jvm and iOS in addition to Android.
paging-testing
has moved its code to
common
and is now compatible with jvm and iOS in addition to Android.
paging-compose
has moved its code to
common
and ships an Android artifact, matching the multiplatform support of
androidx.compose
.
paging-runtime
,
paging-guava
,
paging-rxjava2
, and
paging-rxjava3
will remain Android only.
Version 3.3.0-rc01
May 1, 2024
androidx.paging:paging-*:3.3.0-rc01
is released with no changes in Paging 3.3.0-beta01. Version 3.3.0-rc01 contains
these commits
.
Version 3.3.0-beta01
April 3, 2024
androidx.paging:paging-*:3.3.0-beta01
is released with no notable changes. Version 3.3.0-beta01 contains
these commits
.
Version 3.3.0-alpha05
March 20, 2024
androidx.paging:paging-*:3.3.0-alpha05
is released. Version 3.3.0-alpha05 contains
these commits
.
API Changes
- Paging now uses the AndroidX Annotation
@MainThread
annotation for common code. (
I78f0d
,
b/327682438
)
Version 3.3.0-alpha04
March 6, 2024
androidx.paging:paging-*:3.3.0-alpha04
is released. Version 3.3.0-alpha04 contains
these commits
.
Bug Fixes
- Fixed minor documentation errors related to the addition of Kotlin multiplatform compatibility. (
aosp/2950785
)
Version 3.3.0-alpha03
February 7, 2024
androidx.paging:paging-*:3.3.0-alpha03
is released.
Version 3.3.0-alpha03 contains these commits.
New Features
PagingDataPresenter
is now a public class. Multiplatform presenters can now be built on top of
PagingDataPresenter
rather than requiring internal Paging APIs or
paging-runtime
’s
AsyncPagingDataDiffer
. (
Id1f74
,
b/315214786
)
- Added new
LoadStates
and
CombinedLoadStates
helper methods to check if
LoadStates
is in Error or
NotLoading
state. Also added a new API that awaits on a
LoadStateFlow
until a load has settled into either
NotLoading
or Error state. (
Id6c67
)
Behavior change
PagingData.empty()
now dispatches
NotLoading
states by default unless custom
LoadStates
are passed to its constructor. This departs from existing behavior where it doesn't dispatch
LoadStates
when submitted to a
PagingDataAdapter
or it dispatches Loading states when collected as
LazyPagingItems
. When collected as
LazyPagingItems
, it will now also display an empty list immediately upon initial composition. (
I4d11d
,
b/301833847
)
Version 3.3.0-alpha02
September 20, 2023
androidx.paging:paging-*:3.3.0-alpha02
is released.
Version 3.3.0-alpha02 contains these commits.
Kotlin Multiplatform Compatibility
Paging now ships artifacts compatible with Kotlin Multiplatform, thanks in large part to upstreamed work from CashApp's
multiplatform-paging
project. This will allow us to avoid divergence between two repositories and keep them compatible.
paging-common
has moved all Paging 3 APIs to
common
and is now compatible with jvm and iOS in addition to Android.
paging-testing
has moved its code to
common
and is now compatible with jvm and iOS in addition to Android.
paging-compose
has moved its code to
common
and ships an Android artifact, matching the multiplatform support of
androidx.compose
.
paging-runtime
,
paging-guava
,
paging-rxjava2
, and
paging-rxjava3
will remain Android only.
API Changes
- The public Logger interface that was meant only for internal usage has been deprecated (
I16e95
,
b/288623117
)
External Contribution
- Thanks
veyndan
from Cash App for helping move Paging to Kotlin Multiplatform (
#560
,
#561
,
#562
,
#573
,
#576
,
#577
,
#578
,
#579
,
#580
,
#581
,
#583
,
#584
,
#586
,
#609
)
Version 3.3.0-alpha01
September 20, 2023
- This is the first multiplatform release of androidx.paging libraries. This version only has
*-jvm
, and
*-android
artifacts. For macOS, iOS, and linux variants, use
3.3.0-alpha02
.
Version 3.2
Version 3.2.1
September 6, 2023
androidx.paging:paging-*:3.2.1
is released.
Version 3.2.1 contains these commits.
Bug Fixes
- Fixed an issue where the
asSnapshot()
API of the Paging Testing artifact would hang when passed a Flow built using
PagingData.from(List)
since
asSnapshot()
would not have any information on when loading has finished (unlike the
PagingData.from(List, LoadStates)
overload). This workaround only works for completable Flows (e.g., a
flowOf(PagingData.from(...))
). For non-completable Flows (e.g.,
MutableStateFlow
, use the
PagingData.from
overload that provides
LoadStates
). (
I502c3
)
- Paging Compose now internally uses
AndroidUiDispatcher.Main
to ensure that new data is available in the same frame as loading completes. (
Ia55af
)
Version 3.2.0
July 26, 2023
androidx.paging:paging-*:3.2.0
is released.
Version 3.2.0 contains these commits.
Important changes since 3.1.0
- Paging Compose reached API stability and has been merged back into the rest of Paging where its version now matches all the other Paging artfacts. Changes since 3.1.0 include:
- Support for previewing a list of fake data by creating a
PagingData.from(fakeData)
and wrapping that
PagingData
in a
MutableStateFlow
(e.g.
MutableStateFlow(PagingData.from(listOf(1, 2, 3)))
). Pass this flow into
@Preview
composables as receiver for
collectAsLazyPagingItems()
to preview.
- Support for all lazy layouts such as
LazyVerticalGrid
and
HorizontalPager
as well as custom lazy components from Wear and TV libraries. This was achieved through new lower level
LazyPagingItems
extension methods
itemKey
and
itemContentType
, which helps you implement the
key
and
contentType
parameters to the standard
items
APIs that already exist for
LazyColumn
,
LazyVerticalGrid
as well as their equivalents in APIs like
HorizontalPager
.
items(lazyPagingItems)
and
itemsIndexed(lazyPagingItems)
which only supports
LazyListScope
were deprecated.
- New
paging-testing
artifact which provides APIs designed around unit testing each layer of your app and its integration with Paging in isolation. For example, it includes
TestPager
class that allows you to validate the behavior of your own custom
PagingSource
implementation independently from the Pager and real UI.
- ??
asPagingSourceFactory
APIs to transform either a
Flow<List<Value>>
or a static
List<Value>
into a
PagingSourceFactory
that can be passed to a Pager in tests
asSnapshot
Kotlin extension on
Flow<PagingData<Value>>
, which translates the
Flow<PagingData<Value>>
into a direct
List<Value>
. The
asSnapshot lambda
allows you to mimic the UI of your app via APIs such as
scrollTo
or
appendScrollWhile
so that you can verify the snapshot of data is correct at any point in your set of paged data.
- Added default logs to expose Paging debugging information in two levels:
VERBOSE
and
DEBUG
. The logs can be enabled via the command
adb shell setprop log.tag.Paging [DEBUG|VERBOSE]
. This applies to both Paging with views or Paging with Compose.
- Added constructors for
PagingDataAdapter
and
AsyncPagingDataDiffer
which accept
CoroutineContext
instead of
CoroutineDispatcher
.
- Added a new
PagingSourceFactory
functional interface that provides a more explicit API surface than the previous () ->
PagingSource
lambdas. This factory can be used to instantiate a Pager.
Version 3.2.0-rc01
June 21, 2023
androidx.paging:paging-*:3.2.0-rc01
is released.
Version 3.2.0-rc01 contains these commits.
External Contribution
Version 3.2.0-beta01
June 7, 2023
androidx.paging:paging-*:3.2.0-beta01
is released.
Version 3.2.0-beta01 contains these commits.
Paging Compose
- Paging Compose has officially reached API stability. As such, the version has been updated from
1.0.0-alpha20
to now match the version of all other Paging artifacts.
API Changes
Version 3.2.0-alpha06
May 24, 2023
androidx.paging:paging-*:3.2.0-alpha06
is released.
Version 3.2.0-alpha06 contains these commits.
New Features
- Added a new
PagingSourceFactory
functional interface that provides a more explicit API surface than the existing
() -> PagingSource
lambdas. This factory can be used to instantiate a
Pager
. (
I33165
,
b/280655188
)
- Added new
paging-testing
API of
List<Value>.asPagingSourceFactory()
to get a
PagingSourceFactory
that only loads from an immutable list of data. The existing extension on
Flow<List<Value>>
should still be used for testing with multiple generations of static data. (
Id34d1
,
b/280655188
)
API Changes
- All public APIs in paging-testing are now annotated with
@VisibleForTesting
to ensure these APIs are used only in tests. (
I7db6e
)
- The
asSnapshot
API no longer requires passing in a
CoroutineScope
. It now defaults to using the context inherited from its parent scope. (
Id0a78
,
b/282240990
)
- Reordered
TestPager
constructor parameters to intuitively match the order of real
Pager
constructor parameters (
I6185a
)
- Migrated paging-testing's use of lambda type
() -> PagingSource<Key, Value>
to type
PagingSourceFactory<Key, Value>
. (
I4a950
,
b/280655188
)
Behavior Changes
- Main dispatcher is no longer required to run
asSnapshot
Paging tests. Setting it no longer makes any changes to the test behavior. (
Ie56ea
)
Version 3.2.0-alpha05
May 3, 2023
androidx.paging:paging-*:3.2.0-alpha05
is released.
Version 3.2.0-alpha05 contains these commits.
API Changes
- The Paging Testing API of
asSnapshot
now defaults its
loadOperations
parameter to an empty lambda. This allows calling
asSnapshot
without passing in any load operations to retrieve the data from the initial refresh load. (
Ied354
,
b/277233770
)
Documentation Improvements
- Updated the documentation on
asPagingSourceFactory()
to clarify that it is an extension method on a
Flow
which returns a reusable factory for generating
PagingSource
instances. (
I5ff4f
,
I705b5
)
- Updated the documentation on the
LoadResult.Page
constructor to clarify the need to override
itemsBefore
and
itemsAfter
to support jumping. (
Ied354
)
External Contributions
- Thanks
Veyndan
for contributing to moving Paging away from Android/JVM specifics. (
#525
,
#523
,
#520
,
#519
,
#507
,
#506
,
#505
,
#499
,
#497
,
#496
,
#493
)
Version 3.2.0-alpha04
February 8, 2023
androidx.paging:paging-*:3.2.0-alpha04
is released.
Version 3.2.0-alpha04 contains these commits.
Paging Testing
- The
paging-testing
artifact now contains a
asPagingSourceFactory
method to create a
pagingSourceFactory
from a
Flow<List<Value>>
to be supplied to a Pager. Each
List<Value>>
emitted from the Flow represents a generation of Paged data. This facilitates paging tests on, for example,
PagingData
transformations by faking a data source for the Pager to collect from. (
I6f230
,
b/235528239
)
The
paging-testing
artifact has been expanded with new APIs suitable for verifying the data contained with a
Flow<PagingData<T>>
is correct. This can be used, for example, to assert the output of a
Flow<PagingData<T>>
from your ViewModel layer.
This is done via the
asSnapshot
Kotlin extension on
Flow<PagingData<Value>>
, which translates the
Flow<PagingData<Value>>
into a direct
List<Value>
. The
asSnapshot
lambda allows you to mimic the UI of your app via APIs such as
scrollTo
or
appendScrollWhile
in a way that is repeatable and consistent so that you can verify the snapshot of data is correct at any point in your set of paged data.
// Create your ViewModel instance
val viewModel = …
// Get the Flow of PagingData from the ViewModel
val data< Flow<PagingData<String>> = viewModel.data
val snapshot: List<String> = data.asSnapshot {
// Each operation inside the lambda waits for the data to settle before continuing
scrollTo(index = 50)
// While you can’t view the items within the asSnapshot call,
// you can continuously scroll in a direction while some condition is true
// i.e., in this case until you hit a placeholder item
appendScrollWhile { item: String -> item != “Header 1” }
}
// With the asSnapshot complete, you can now verify that the snapshot
// has the expected values
asSnapshot
is a
suspend
method that is expected to be run within
runTest
. See
Testing Kotlin coroutines on Android
for more information. (
I55fd2
,
I5bd26
,
I7ce34
,
I51f4d
,
I2249f
,
Id6223
,
Ic4bab
,
Ib29b9
,
Ic1238
,
I96def
,
b/235528239
)
API Changes
- UI calls to
getItem
and
peek
in
AsyncPagingDataDiffer
and
PagingDataAdapter
are now correctly marked as only callable on the Main thread. (
I699b6
)
- Removed wildcards from generic types used by
TestPager
, making it easier to consume the results of those methods in code written in the Java programming language. (
I56c42
)
Version 3.2.0-alpha03
October 24, 2022
androidx.paging:paging-*:3.2.0-alpha03
is released.
Version 3.2.0-alpha03 contains these commits.
Paging Testing
This release contains a new artifact:
paging-testing
. This artifact provides APIs designed around unit testing each layer of your app and its integration with Paging in isolation.
For example, this first release includes a
TestPager
class that allows you to validate the behavior of your own custom
PagingSource
implementation independently from the
Pager
and real UI you would normally need to simulate the end-to-end Paging integration.
TestPager
should be considered a
fake
- a
test double
that mirrors the real implementation of
Pager
while providing a simplified API surface for testing a
PagingSource
. These APIs are
suspend
APIs and should be run within
runTest
as outlined in the guide for
Testing Kotlin coroutines on Android
.
An example of these APIs in use can be found in the
room-paging
tests
, which were refactored to use
TestPager
.
API Changes
- Enables convenient iteration over
LoadResult.Page.data
through
LoadResult.Page.iterator()
. This indirectly allows the usage of the
Kotlin standard library
flatten
method
when given a
List<LoadResult.Page>
such as with the
pages
property of
PagingState
that is passed to the
PagingSource.getRefreshKey
method. (
Ie0718
)
Version 3.2.0-alpha02
August 10, 2022
androidx.paging:paging-*:3.2.0-alpha02
is released.
Version 3.2.0-alpha02 contains these commits.
New Features
- Paging now provides logs via the
AsyncPagingDataDiffer
or
PagingDataAdapter
classes to expose debugging information collected from
PagingData
.
- The logs can be enabled via the
adb shell
command
adb shell setprop log.tag.Paging [DEBUG|VERBOSE].
(
b/235527159
)
Bug Fixes
- Fixed the missing
PagingDataDiffer
constructor error when using
paging-common:3.2.0-alpha01
with runtime
paging-runtime:3.1.1
or older.(
b/235256201
)
Version 3.2.0-alpha01
June 1, 2022
androidx.paging:paging-*:3.2.0-alpha01
is released.
Version 3.2.0-alpha01 contains these commits.
API Changes
- Added constructors for
PagingDataAdapter
and
AsyncPagingDataDiffer
which accept
CoroutineContext
instead of
CoroutineDispatcher
. (
Idc878
)
- By default,
PagingData.from()
and
PagingData.empty()
will no longer affect
CombinedLoadStates
on the presenter side. A new overload that allows passing
sourceLoadStates
and
remoteLoadStates
in to these constructors has been added to maintain the existing behavior of setting
LoadStates
to be fully terminal (i.e.,
NotLoading(endOfPaginationReached = false)
), with the option to include remote states as well if needed. If
LoadStates
are not passed, then the previous
CombinedLoadStates
will be maintained on the presenter side when it receives the static
PagingData
. (
Ic3ce5
,
b/205344028
)
Bug Fixes
- The result of
PagingSource.getRefreshKey()
is now correctly priotized over
initialKey
in cases where it would return null, but a non-null
initialKey
was set. (
Ic9542
,
b/230391606
)
External Contribution
- Updated :compose:ui:ui-test api (updateApi) due to test-coroutines-lib migration (
I3366d
)
Version 3.1
Version 3.1.1
March 9, 2022
androidx.paging:paging-*:3.1.1
is released.
Version 3.1.1 contains these commits.
Bug Fixes
- Removed intermediate
LoadState.NotLoading
events between generations that were incorrectly inserted by
.cachedIn()
. This change makes it much easier to react on
LoadState
changes by removing redundant
LoadState.NotLoading
events that were produced between retrying failed loads, when refreshing or during invalidation.
Version 3.1.0
November 17, 2021
androidx.paging:paging-*:3.1.0
is released.
Version 3.1.0 contains these commits.
Important changes since 3.0.0
Flow<PagingData>.observable
and
Flow<PagingData>.flowable
APIs are no longer experimental
- Behavior changes to
LoadState
:
endOfPaginationReached
is now always
false
for
LoadType.REFRESH
for both
PagingSource
and
RemoteMediator
LoadStates
from Paging now await valid values from both
PagingSource
and
RemoteMediator
before emitting downstream. New generations of
PagingData
will now always correctly begin with
Loading
for refresh state instead of resetting to
NotLoading
incorrectly in some cases.
.loadStateFlow
and
.addLoadStateListener
on presenter APIs no longer redundantly send an initial
CombinedLoadStates
that always has mediator states set to
null
- Cancellation on past generations now happens eagerly on invalidation / new generations. It should no longer be required to use
.collectLatest
on
Flow<PagingData>
, although it is still recommended to do so.
PagingSource.LoadResult.Invalid
has been added as a new return type from
PagingSource.load
, which causes Paging to discard any pending or future load requests to this
PagingSource
and invalidate it. This return type is designed to handle potentially invalid or stale data that can be returned from the database or network.
- Added
.onPagesPresented
and
.addOnPagesUpdatedListener
presenter APIs which triggered synchronously as pages are presented in UI. Page updates can happen in the following scenarios:
- Initial load of a new generation of PagingData completes, regardless if the new generation contains any changes to the presented items. i.e., A new generation completing initial load with no updates because the list is exactly the same will still trigger this callback.
- A page is inserted, even if the inserted page contains no new items.
- A page is dropped, even if the dropped page was empty.
Version 3.1.0-rc01
November 3, 2021
androidx.paging:paging-*:3.1.0-rc01
is released.
Version 3.1.0-rc01 contains these commits.
Bug Fixes
- Fixed a race condition + memory leak in .cachedIn() in cases where multiple load events were sent by Paging downstream while there are no observers or between when an observer is switching to a new PagingData. (
Ib682e
)
Version 3.1.0-beta01
October 13, 2021
androidx.paging:paging-*:3.1.0-beta01
is released.
Version 3.1.0-beta01 contains these commits.
Bug Fixes
- Fixed an issue where many rapid item accesses could cause them to get dropped for consideration in prefetchDistance, causing page loads to stall. This is especially an issue when many items are laid out at once in an order which would prioritize loading against the user scroll direction. These item accesses are now buffered and synchronously prioritized to prevent them from getting dropped. (
aosp/1833273
)
Version 3.1.0-alpha04
September 29, 2021
androidx.paging:paging-*:3.1.0-alpha04
is released.
Version 3.1.0-alpha04 contains these commits.
API Changes
Flow<PagingData>.observable
and
Flow<PagingData>.flowable
APIs
are no longer experimental. (
Ie0bdd
)
Bug Fixes
- For LoadStates,
endOfPaginationReached
is now always
false
for
LoadType.REFRESH
. Previously, it was possible for
endOfPaginationReached to be
true
for RemoteMediator
REFRESH
, but not
for PagingSource. This behavior is now consolidated to always return
false
as it never makes sense for REFRESH to be terminal, and is now
documented as part of the API contract in LoadStates. When deciding if
pagination is terminated, you should always do so with respect to
either the APPEND or PREPEND directions. (
I047b6
)
LoadStates from Paging now await valid values from both
PagingSource and RemoteMediator before emitting downstream between
generations. This prevents new generations of PagingData from sending
NotLoading in CombinedLoadStates.source.refresh if it was already
Loading; new generations of PagingData will now always correctly begin
with Loading for refresh state instead of first resetting to NotLoading
incorrectly in some cases.
Cancellation on past generations now happen eagerly on invalidation /
new generations. It should no longer be required to use .collectLatest
on
Flow<PagingData>
, although it is still highly recommended to do so. (
I0b2b5
,
b/177351336
,
b/195028524
)
.loadStateFlow
and
.addLoadStateListener
on presenter APIs
no longer redundantly send an initial
CombinedLoadStates
that always
has mediator states set to
null
and source states set to
NotLoading(endOfPaginationReached = false)
. This means that:
- mediator states will always be populated if you use RemoteMediator.
- Registering a new loadState listener or a new collector on
.loadStateFlow
will no longer immediately emit the current value
if it hasn't received a real
CombinedLoadStates
from
PagingData
. This can happen if a collector or listener starts
before a
PagingData
has been submitted. (
I1a748
)
Version 3.1.0-alpha03
July 21, 2021
androidx.paging:paging-*:3.1.0-alpha03
is released.
Version 3.1.0-alpha03 contains these commits.
API Changes
A third LoadResult return type LoadResult.Invalid is added to
PagingSource. When a PagingSource.load returns
LoadResult.Invalid, paging will discard the loaded data and
invalidate the PagingSource. This return type is designed to
handle potentially invalid or stale data that can be returned
from the database or network.
For example, if the underlying database gets written into but
the PagingSource does not invalidate in time, it may return
inconsistent results if its implementation depends on the
immutability of the backing dataset it loads from (e.g., LIMIT
OFFSET style db implementations). In this scenario, it is
recommended to check for invalidation after loading and to
return LoadResult.Invalid, which causes Paging to discard any
pending or future load requests to this PagingSource and
invalidate it.
This return type is also supported by Paging2 API that leverages
LivePagedList or RxPagedList. When using a PagingSource with
Paging2's PagedList APIs, the PagedList is immediately detached,
stopping further attempts to load data on this PagedList and
triggers invalidation on the PagingSource.
LoadResult is a sealed class, which means this is a
source-incompatible change such that use cases directly using
PagingSource.load results will have to handle LoadResult.Invalid
at compile time. For example, Kotlin users leveraging
exhaustive-when to check return type will have to add a check
for Invalid type. (
Id6bd3
,
b/191806126
,
b/192013267
)
Bug Fixes
- Invalidation callbacks added via
PagingSource.registerInvalidatedCallback or
DataSource.addInvalidatedCallback now automatically trigger if they
were registered on a PagingSource / DataSource that was already
invalid. This resolves a race condition which caused Paging to drop
invalidation signals and get stuck when provided a Source which was
already invalid during initial load. Additionally, invalidate
callbacks are now properly removed after being triggered as they are
guaranteed to be called at most once. (
I27e69
)
- Submitting the placeholder initial value (InitialPagedList) from a newly instantiated PagedList stream, e.g., LivePagedListBuilder or RxPagedListBuilder will no longer clear previously loaded data.
Version 3.1.0-alpha02
July 1, 2021
androidx.paging:paging-*:3.1.0-alpha02
is released.
Version 3.1.0-alpha02 contains these commits.
New Features
Added onPagesPresented listener and flow presenter APIs
which trigger immediately after presented pages are updated in UI.
Since these updates are synchronous with UI, you may call adapter methods
such as .snapshot, .getItemCount, to inspect the state after the
update has been applied. Note that .snapshot() was left to be
explicitly called because it can be expensive to do on every update.
Page updates can happen in the following scenarios:
- Initial load of a new generation of PagingData completes,
regardless if the new generation contains any changes to the
presented items. i.e., A new generation completing initial load
with no updates because the list is exactly the same will still
trigger this callback.
- A page is inserted, even if the inserted page contains no new
items
- A page is dropped, even if the dropped page was empty (
I272c9
,
b/189999634
)
Bug Fixes
- Accessing PagedList.dataSource from the initial value produced
by LivePagedList or RxPagedList will no longer incorrectly throw an
IllegalStateException (
I96707
)
Version 3.1.0-alpha01
June 2, 2021
androidx.paging:paging-*:3.1.0-alpha01
is released.
Version 3.1.0-alpha01 contains these commits.
API Changes
- Classes provided by
paging-rxjava3
now live under the
androidx.paging.rxjava3
package so that they do not conflict with
paging-rxjava2
(
Ifa7f6
)
Bug Fixes
- Fixed an issue where Paging would sometimes send no-op differ
events to RecyclerView, which could cause certain listeners to trigger
early. (
Ic507f
,
b/182510751
)
External Contribution
Paging Compose Version 1.0.0
Version 1.0.0-alpha20
May 24, 2023
androidx.paging:paging-compose:1.0.0-alpha20
is released.
Version 1.0.0-alpha20 contains these commits.
New Features
- Paging Compose now supports previewing a list of fake data by creating a
PagingData.from(fakeData)
and wrapping that
PagingData
in a
MutableStateFlow
(e.g.,
MutableStateFlow(PagingData.from(listOf(1, 2, 3)))
). By using that data as the input into your
@Preview
, calls to
collectAsLazyPagingItems()
will provide previewable
LazyPagingItems
. (
I8a78d
,
b/194544557
)
Bug Fixes
- Cached data from
pager.flow.cachedIn
that has been collected in
LazyPagingItems
will now be immediately available after state restoration without requiring asynchronous collection. This means the cached data will be ready for presentation immediately upon initial composition after state is restored. (
I97a60
,
b/177245496
)
Version 1.0.0-alpha19
May 3, 2023
androidx.paging:paging-compose:1.0.0-alpha19
is released.
Version 1.0.0-alpha19 contains these commits.
Supporting all lazy layouts
Previously, Paging Compose provided custom
items
and
itemsIndexed
extensions on
LazyListScope
, which meant that you could not use Paging Compose with other lazy layouts like
LazyVerticalGrid
,
HorizontalPager
, or other custom lazy components provided by the Wear and TV libraries. Addressing this inflexibility is the primary update for this release.
To support more lazy layouts, we needed to build out APIs at a different layer - rather than providing a custom
items
API for each lazy layout, Paging Compose now provides slightly lower level extension methods on
LazyPagingItems
in
itemKey
and
itemContentType
. These APIs focus on helping you implement the
key
and
contentType
parameters to the standard
items
APIs that already exist for
LazyColumn
,
LazyVerticalGrid
as well as their equivalents in APIs like
HorizontalPager
. (
Ifa13b
,
Ib04f0
,
b/259385813
)
This means that supporting a
LazyVerticalGrid
would look like:
// This part is unchanged
val lazyPagingItems = pager.collectAsLazyPagingItems()
LazyVerticalGrid(columns = GridCells.Fixed(2)) {
// Here we use the standard items API
items(
count = lazyPagingItems.itemCount,
// Here we use the new itemKey extension on LazyPagingItems to
// handle placeholders automatically, ensuring you only need to provide
// keys for real items
key = lazyPagingItems.itemKey { it.uniqueId },
// Similarly, itemContentType lets you set a custom content type for each item
contentType = lazyPagingItems.itemContentType { "contentType" }
) { index ->
// As the standard items call provides only the index, we get the item
// directly from our lazyPagingItems
val item = lazyPagingItems[index]
PagingItem(item = item)
}
}
For more examples of using these new APIs, please see
our samples
.
While these changes do make the
LazyColumn
and
LazyRow
examples a few lines longer, we felt that consistency across all lazy layouts was an important factor for those using Paging Compose going forward. For that reason, the existing extensions to
LazyListScope
have now been deprecated. (
I0c459
,
I92c8f
,
b/276989796
)
API Changes
- To ease the migration to the new APIs, the
items
and
itemsIndexed
extension functions on
LazyListScope
now support a
contentType
parameter, mirroring the support in the new APIs. (
Ib1918
,
b/255283378
)
Dependency Updates
- Paging Compose has updated its dependency from Compose 1.0.5 to Compose 1.2.1. (
Ib1918
,
b/255283378
)
Version 1.0.0-alpha18
February 8, 2023
androidx.paging:paging-compose:1.0.0-alpha18
is released with no changes.
Version 1.0.0-alpha18 contains these commits.
Version 1.0.0-alpha17
October 24, 2022
androidx.paging:paging-compose:1.0.0-alpha17
is released.
Version 1.0.0-alpha17 contains these commits.
New Features
Version 1.0.0-alpha16
August 10, 2022
androidx.paging:paging-compose:1.0.0-alpha16
is released.
Version 1.0.0-alpha16 contains these commits.
New Features
- Paging now provides logs via the
LazyPagingItems
class to expose debugging information collected from PagingData.
- The logs can be enabled via the
adb shell
command
adb shell setprop log.tag.Paging [DEBUG|VERBOSE]
. ([b/235527159}(https://issuetracker.google.com/issues/235527159))
Bug Fixes
- Fixed the missing
PagingDataDiffer
constructor error when using
paging-compose:1.0.0-alpha15
with
paging-common:3.1.1
or older.(
b/235256201
,
b/239868768
)
Version 1.0.0-alpha15
June 1, 2022
androidx.paging:paging-compose:1.0.0-alpha15
is released.
Version 1.0.0-alpha15 contains these commits.
API Changes
- Added constructors for
PagingDataAdapter
and
AsyncPagingDataDiffer
which accept
CoroutineContext
instead of
CoroutineDispatcher
. (
Idc878
)
Bug Fixes
LazyPagingItems
now sets the initial
loadState
to have a
LoadState.Loading
refresh. (
I55043
,
b/224855902
)
Version 1.0.0-alpha14
October 13, 2021
androidx.paging:paging-compose:1.0.0-alpha14
is released.
Version 1.0.0-alpha14 contains these commits.
Version 1.0.0-alpha13
September 29, 2021
androidx.paging:paging-compose:1.0.0-alpha13
is released.
Version 1.0.0-alpha13 contains these commits.
API Changes
LazyPagingItems.snapshot()
function was replaced with
LazyPagingItems.itemSnapshotList
property (
Ie2da8
)
- Deprecated
LazyPagingItems.getAsState()
was removed (
Ie65e4
)
Version 1.0.0-alpha12
July 21, 2021
androidx.paging:paging-compose:1.0.0-alpha12
is released.
Version 1.0.0-alpha12 contains these commits.
API Changes
items(lazyPagingItems)
and
itemsIndexed(lazyPagingItems)
used to connect Paging with
LazyColumn/Row
now accept the option key param which allows you to specify a stable key representing the item. You can read more about keys
here.
(
I7986d
)
- Function
lazyPagingItems.getAsState(index)
is now deprecated. Use
lazyPagingItems[index]
instead. (
I086cb
,
b/187339372
)
Version 1.0.0-alpha11
June 30, 2021
androidx.paging:paging-compose:1.0.0-alpha11
is released.
Version 1.0.0-alpha11 contains these commits.
Version 1.0.0-alpha10
June 2, 2021
androidx.paging:paging-compose:1.0.0-alpha10
is released.
Version 1.0.0-alpha10 contains these commits.
Version 1.0.0-alpha09
May 18, 2021
androidx.paging:paging-compose:1.0.0-alpha09
is released.
Version 1.0.0-alpha09 contains these commits.
Bug Fixes
- LazyPagingItems' itemCount and item getter are now observable which allows it to be used with LazyVerticalGrid as well (
Ie2446
,
b/171872064
,
b/168285687
)
Compose Compatibility
androidx.paging:paging-compose:1.0.0-alpha09
is only compatible with Compose version
1.0.0-beta07
and above.
Version 1.0.0-alpha08
February 24, 2021
androidx.paging:paging-compose:1.0.0-alpha08
is released.
Version 1.0.0-alpha08 contains these commits.
Updated to integrate with Compose 1.0.0-beta01.
Version 1.0.0-alpha07
February 10, 2021
androidx.paging:paging-compose:1.0.0-alpha07
is released.
Version 1.0.0-alpha07 contains these commits.
Updated to integrate with Compose alpha12.
Version 1.0.0-alpha06
January 28, 2021
androidx.paging:paging-compose:1.0.0-alpha06
is released.
Version 1.0.0-alpha06 contains these commits.
Bug Fixes
Updated to depend on Compose 1.0.0-alpha11.
Version 1.0.0-alpha05
January 13, 2021
androidx.paging:paging-compose:1.0.0-alpha05
is released.
Version 1.0.0-alpha05 contains these commits.
Updated to depend on Compose 1.0.0-alpha10.
Version 1.0.0-alpha04
December 16, 2020
androidx.paging:paging-compose:1.0.0-alpha04
is released.
Version 1.0.0-alpha04 contains these commits.
Bug Fixes
- Updated the convenience properties,
CombinedLoadStates.refresh
,
CombinedLoadStates.prepend
,
CombinedLoadStates.append
to only transition from
Loading
to
NotLoading
after both mediator and source load states are
NotLoading
to ensure the
remote update has been applied. (
I65619
)
Version 1.0.0-alpha03
December 2, 2020
androidx.paging:paging-compose:1.0.0-alpha03
is released.
Version 1.0.0-alpha03 contains these commits.
- Updated to match Compose 1.0.0-alpha08.
Version 1.0.0-alpha02
November 11, 2020
androidx.paging:paging-compose:1.0.0-alpha02
is released.
Version 1.0.0-alpha02 contains these commits.
API Changes
- Added
.peek()
,
.snapshot()
,
.retry()
and
.refresh()
methods to
LazyPagingItem
s which expose the same functionality available in
AsyncPagingDataDiffer
/
PagingDataAdapter
(
Iddfe8
,
b/172041660
)
Version 1.0.0-alpha01
October 28, 2020
androidx.paging:paging-compose:1.0.0-alpha01
is released.
Version 1.0.0-alpha01 contains these commits.
New Features
The
paging-compose
artifact provides integration between
The Paging Library
and
Jetpack Compose
. A simple usage example:
@Composable
@OptIn(ExperimentalLazyDsl::class)
fun ItemsDemo(flow: Flow<PagingData<String>>) {
val lazyPagingItems = flow.collectAsLazyPagingItems()
LazyColumn {
items(lazyPagingItems) {
Text("Item is $it")
}
}
}
Version 3.0.1
Version 3.0.1
July 21, 2021
androidx.paging:paging-*:3.0.1
is released.
Version 3.0.1 contains these commits.
Bug Fixes
- Accessing
PagedList.dataSource
from the initial value produced by
LivePagedList
or
RxPagedList
will no longer incorrectly throw an IllegalStateException (
I96707
)
Version 3.0.0
Version 3.0.0
May 5, 2021
androidx.paging:paging-*:3.0.0
is released.
Version 3.0.0 contains these commits.
Major features of 3.0.0
The majority of the existing API from Paging 2.x.x has been deprecated in favor of the new Paging 3 APIs to bring the following improvements:
- First-class support for Kotlin coroutines and Flow
- Support for cancellation
- Built-in load state and error signals
- Retry + refresh functionality
- All three DataSource subclasses have been combined into a unified PagingSource class
- Custom page transformations including a built-in one for adding separators
- Loading state headers and footers
Version 3.0.0-rc01
April 21, 2021
androidx.paging:paging-*:3.0.0-rc01
is released.
Version 3.0.0-rc01 contains these commits.
Bug Fixes
- Fixed an issue where Paging would sometimes send no-op differ
events to RecyclerView, which could cause certain listeners to trigger
early. (
Ic507f
,
b/182510751
)
Version 3.0.0-beta03
March 24, 2021
androidx.paging:paging-*:3.0.0-beta03
is released.
Version 3.0.0-beta03 contains these commits.
Bug Fixes
- We've revamped how placeholders are handled when list is
reloaded to prevent unexpected jumps in RecyclerView. See
NullPaddedDiffing.md
for details. (
If1490
,
b/170027529
,
b/177338149
)
- The various PagedList builders (old compatibility path) no longer incorrectly synchronously call
DataSource.Factory.create()
on Main thread when
.build()
is called. (
b/182798948
)
Version 3.0.0-beta02
March 10, 2021
androidx.paging:paging-*:3.0.0-beta02
is released.
Version 3.0.0-beta02 contains these commits.
API Changes
- Rx3 extensions now correctly propagate
@ExperimentalCoroutinesApi
Opt-In requirement. Previously they were
marked on the
@get
method, which is ignored by the Kotlin Compiler due
to: https://youtrack.jetbrains.com/issue/KT-45227 (
I5733c
)
Bug Fixes
- Enforce restrictions on public usage of experimental APIs (
I6aa29
,
b/174531520
)
- Fixed a bug causing
PagingState
to always be
null
when
remote refresh is called.
- Fixed a bug where empty pages returned by PagingSource could prevent Paging from fetching again to fulfill
prefetchDistance
causing Paging to get “stuck”.
Version 3.0.0-beta01
February 10, 2021
androidx.paging:paging-*:3.0.0-beta01
is released.
Version 3.0.0-beta01 contains these commits.
API Changes
- Rx2 and Rx3 wrappers now expose the experimental annotation it
depends on. If you are using the Rx compat wrappers in paging-rxjava2 or
paging-rxjava3, you will now need to annotate usages with
@OptIn(ExperimentalCoroutinesApi::class)
(
Ib1f9d
)
Bug Fixes
- Fixed
IndexOutOfBoundsException: Inconsistency detected
sometimes thrown when using v2
DataSource
APIs through compatibility paths
isInvalid
call during initialization of
DataSource
when used via compatibility paths are now correctly launched on fetchDispatcher instead of on the main thread. This fixes an
IllegalStateException
due to Db access on the main thread when using Room’s
PagingSource
implementation.
Version 3.0.0-alpha13
January 27, 2021
androidx.paging:paging-*:3.0.0-alpha13
is released.
Version 3.0.0-alpha13 contains these commits.
API Changes
PagingSource.getRefreshKey
is no longer optional to implement,
it is now an abstract function without a default implementation.
Migrating users can either continue returning the default
implementation, which simply returns
null
, but
getRefreshKey()
should have a real implementation returning a key based on user's
current scroll position that allows Paging to continue loading
centered around the viewport via
PagingState.anchorPosition
if
possible. (
I4339a
)
InvalidatingPagingSourceFactory
is now a final class (
Ia3b0a
)
- Allow configuration of terminal separator (header / footer)
behavior with an additional optional SeparatorType parameter. The two
options are:
FULLY_COMPLETE
- existing behavior; wait for both PagingSource and
RemoteMediator to mark endOfPaginationReached before adding terminal
separators. If RemoteMediator is not used, remote loadState is
ignored. This is primarily useful if you only want to show section
separators when the section is fully loaded, including fetching from
remote source e.g., network.
SOURCE_COMPLETE
- only wait for PagingSource to mark
endOfPaginationReached even if RemoteMediator is used. This allows
headers and footers to be presented synchronously with the initial
load, which prevents users from needing to scroll to see terminal
separators. (
Ibe993
,
b/174700218
)
Bug Fixes
- Fixed a rare memory leak which happens when a PagingSource is
invalidated before PageFetcher can even begin to start loading from it. (
I9606b
,
b/174625633
)
Version 3.0.0-alpha12
January 13, 2021
androidx.paging:paging-*:3.0.0-alpha12
is released.
Version 3.0.0-alpha12 contains these commits.
API Changes
- InvalidatingPagingSourceFactory is no longer an abstract class
as it never had any abstract methods. (
I4a8c4
)
- Added an overload of .cachedIn() that accepts ViewModel
instead of Lifecycle or CoroutineScope for Java users. (
I97d81
,
b/175332619
)
- Allow Java callers to use PagingData transform operations in
an async way, by accepting an Executor into transform operator
arguments. All of the -Sync transform operators have the -Sync suffix
removed now, and Kotlin Coroutine users will need to disambiguate by
calling the extension function which accepts a suspending block instead.
All PagingData transformation operators have been moved to extensions
under the static PagingDataTransforms class. Java users will need to
call them via static helpers e.g.,
PagingDataTransforms.map(pagingData, transform)
For Kotlin users, the syntax is the same but you'll need to import the
function. (
If6885
,
b/172895919
)
Bug Fixes
- Fixed a bug where
RemoteMediator.load()
would not be called during
adapter.refresh()
if the end of pagination had already been reached.
Version 3.0.0-alpha11
December 16, 2020
androidx.paging:paging-*:3.0.0-alpha11
is released.
Version 3.0.0-alpha11 contains these commits.
New Features
- Saved state support added for the following basic use cases (full support, especially in the layered source case is still a work in progress):
- flow is cached and application is not killed (e.g. flow is cached in a view model and activity is recreated in process)
- paging source is counted, placeholders are enabled and the layout is
not staggered.
API Changes
PagingSource.getRefreshKey()
is now stable API (
I22f6f
,
b/173530980
)
PagingSource.invalidate
is no longer an open function. If you
need to get notified when invalidation happens, consider calling the
registerInvalidatedCallback method instead of overriding invalidate. (
I628d9
,
b/173029013
,
b/137971356
)
- Pager now has a single experimental constructor alongside its
regular constructors, rather than leaking experimental APIs into
non-experimental public API via the opt-in annotation. (
I9dc61
,
b/174531520
)
- Updated the convenience properties,
CombinedLoadStates.refresh
,
CombinedLoadStates.prepend
,
CombinedLoadStates.append
to only transition from
Loading
to
NotLoading
after both mediator and source load states are
NotLoading
to ensure the
remote update has been applied. (
I65619
)
LoadParams.pageSize has been removed (it was already
deprecated).
The recommendation is to use
LoadParams.loadSize
in your PagingSource.
LoadParams.loadSize
is always equal to the
PagingConfig.pageSize
except for the initial load call where it is equal to the
PagingConfig.initialLoadSize
.
If you are testing your Paging2 DataSource without using a Pager or
PagedList,
pageSize
may not match the
PagingConfig.pageSize
if
you are also setting
initialLoadSize
. If it is important for your
tests, try using a Pager/PagedList instead which will internally set
the correct PageSize for your DataSource load methods. (
I98ac7
,
b/149157296
)
Bug Fixes
- Fixed a crash due to IllegalStateException when
using separators with PagingConfig.maxSize set. (
I0ed33
,
b/174787528
)
- Fixed a bug where load state for PREPEND / APPEND would not
update to
NotLoading(endOfPaginationReached = true)
immediately
after initial load if RemoteMediator was set (
I8cf5a
)
- Fixed a bug where presenter-side APIs such as .snapshot(), .peek(), etc., would return the previous (out-of-date) list within ListUpdateCallback updates.
- Fixed a bug where Separators operators would not add headers or footers when used with RemoteMediator
- Fixed a bug where LoadState updates to NotLoading for RemoteMediator would get stuck in the Loading state
- Fixed a bug where the Paging2.0 compatibility API,
.asPagingSourceFactory()
, could cause the backing
DataSource
to be initialized on the incorrect CoroutineDispatcher. This resolves a crash and possible ANR cases, especially when using Room’s current implementation of PagingSource, which uses this compatibility path.
Version 3.0.0-alpha10
December 2, 2020
androidx.paging:paging-*:3.0.0-alpha10
is released.
Version 3.0.0-alpha10 contains these commits.
API Changes
The deprecated
dataRefreshFlow
and
dataRefreshListener
APIs have been removed
as they are redundant with loadStateFlow / Listener updates. For
those migrating, the loadStateFlow equivalent is:
loadStateFlow.distinctUntilChangedBy { it.refresh }
.filter { it.refresh is NotLoading }
(
Ib5570
,
b/173530908
)
Bug Fixes
- endOfPaginationReached for RemoteMediator
REFRESH
now
correctly propagate to LoadState updates and prevents remote
APPEND
and
PREPEND
from triggering. (
I94a3f
,
b/155290248
)
- Presenting an empty list either due to empty initial page or
heavy filtering will no longer prevent Paging from kicking off
PREPEND
or
APPEND
loads. (
I3e702
,
b/168169730
)
- Fixed an issue where
getRefreshKey
does not get called on
subsequent generations of PagingSource when invalidations occur rapidly. (
I45460
,
b/170027530
)
External Contribution
- A new abstract class InvalidatingPagingSourceFactory has been added
with an
.invalidate()
API that forwards invalidate to all of the PagingSources
it emits. Thanks to
@claraf3
! (
Ie71fc
,
b/160716447
)
Known Issues
- Headers and footers from the .insertSeparators() transform may not appear immediately when using RemoteMediator
b/172254056
- Using RemoteMediator can cause remote
LoadState
to get stuck if invalidation and
PagingSource.load(LoadParams.Refresh(...))
completes before
RemoteMediator.load()
returns
b/173717820
Version 3.0.0-alpha09
November 11, 2020
androidx.paging:paging-*:3.0.0-alpha09
is released.
Version 3.0.0-alpha09 contains these commits.
API Changes
- Fully deprecate dataRefreshFlow / Listener methods with a
replaceWith clause. (
I6e2dd
)
Bug Fixes
- Fix for
IllegalArgumentException
being throw when using separators with RemoteMediator and an invalidate is triggered while a remote load that would return endOfPagination is still running (
I3a260
)
Version 3.0.0-alpha08
October 28, 2020
androidx.paging:paging-*:3.0.0-alpha08
is released.
Version 3.0.0-alpha08 contains these commits.
API Changes
- The Kotlin / Java variants of
DataSource.InvalidatedCallback
have been combined by enabling SAM-conversions in Kotlin via functional
interface (available in Kotlin 1.4). This also fixes a bug where the
kotlin variant of invalidate callbacks were not called after transformed
by
.map
or
.mapByPage
. (
I1f244
,
b/165313046
)
Bug Fixes
- Paging’s interaction with ViewPager has been improved considerably. Specifically, Paging will no longer cancel a
RemoteMediator#load
call due to a page invalidation. It will also no longer make an append/prepend load request,
if REFRESH is required
, until REFRESH request completes successfully. (
I6390b
,
b/162252536
)
- API lint check for MissingGetterMatchingBuilder is enabled for androidx (
I4bbea
,
b/138602561
)
- Fixed a bug where
.withLoadState*
ConcatAdapter
helpers would
crash due to notifying RecyclerView from background thread (
I18bb5
,
b/170988309
)
- Fixed a bug where loading a very small non-empty page would sometimes prevent prefetch from triggering loads correctly.
Iffda3
b/169259468
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
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
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
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
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
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
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
Observable
s and
Flowable
s, taking
Scheduler
s instead of
Executor
s:
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
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