# LazyPagingItems

Artifact: [androidx.paging:paging-compose](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/compose/LazyPagingItems.kt+class:androidx.paging.compose.LazyPagingItems) Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0) Common/All
- Cmn

  ```
  class LazyPagingItems<T : Any>
  ```

*** ** * ** ***

The class responsible for accessing the data from a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` of `https://developer.android.com/reference/kotlin/androidx/paging/PagingData`. In order to obtain an instance of `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems` use the `https://developer.android.com/reference/kotlin/androidx/paging/compose/collectAsLazyPagingItems.composable#(kotlinx.coroutines.flow.Flow).collectAsLazyPagingItems(kotlin.coroutines.CoroutineContext)` extension method of `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` with `https://developer.android.com/reference/kotlin/androidx/paging/PagingData`. This instance can be used for Lazy foundations such as `LazyListScope.items` to display data received from the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` of `https://developer.android.com/reference/kotlin/androidx/paging/PagingData`.

Previewing `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems` is supported on a list of mock data. See sample for how to preview mock data.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.sp
import androidx.paging.PagingData
import androidx.paging.compose.collectAsLazyPagingItems

/**
 * The composable that displays data from LazyPagingItems.
 *
 * This composable is inlined only for the purposes of this sample. In production code, this
 * function should be its own top-level function.
 */
@Composable
fun DisplayPaging(flow: Flow<PagingData<String>>) {
    // Flow of real data i.e. flow from a ViewModel, or flow of fake data i.e. from a Preview.
    val lazyPagingItems = flow.collectAsLazyPagingItems()
    LazyColumn(modifier = Modifier.fillMaxSize().background(Color.Red)) {
        items(count = lazyPagingItems.itemCount) { index ->
            val item = lazyPagingItems[index]
            Text(text = "$item", fontSize = 35.sp, color = Color.Black)
        }
    }
}

/**
 * The preview function should be responsible for creating the fake data and passing it to the
 * function that displays it.
 */
// create list of fake data for preview
val fakeData = List(10) { "preview item $it" }
// create pagingData from a list of fake data
val pagingData = PagingData.from(fakeData)
// pass pagingData containing fake data to a MutableStateFlow
val fakeDataFlow = MutableStateFlow(pagingData)
// pass flow to composable
DisplayPaging(flow = fakeDataFlow)
```

| Parameters |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | the type of value used by `https://developer.android.com/reference/kotlin/androidx/paging/PagingData`. |

## Summary

| ### Public functions |
|---|---|---|
| `operator T?` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#get(kotlin.Int)(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns the presented item at the specified position, notifying Paging of the item access to trigger any loads necessary to fulfill prefetchDistance. | Cmn |
| `T?` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#peek(kotlin.Int)(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns the presented item at the specified position, without notifying Paging of the item access that would normally trigger page loads. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#refresh()()` Refresh the data presented by this `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#retry()()` Retry any failed load requests that would result in a `https://developer.android.com/reference/kotlin/androidx/paging/LoadState.Error` update to this `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems`. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#itemCount()` The number of items which can be accessed. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/paging/ItemSnapshotList<T>` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#itemSnapshotList()` Contains the immutable `https://developer.android.com/reference/kotlin/androidx/paging/ItemSnapshotList` of currently presented items, including any placeholders if they are enabled. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/paging/CombinedLoadStates` | `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#loadState()` A `https://developer.android.com/reference/kotlin/androidx/paging/CombinedLoadStates` object which represents the current loading state. | Cmn |

| ### Extension functions |
|---|---|---|
| `(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems<T>.https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#(androidx.paging.compose.LazyPagingItems).itemContentType(kotlin.Function1)(contentType: ((item) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)?)` Returns a factory for the content type of the item. | Cmn |
| `(index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems<T>.https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#(androidx.paging.compose.LazyPagingItems).itemKey(kotlin.Function1)(key: ((item) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html)?)` Returns a factory of stable and unique keys representing the item. | Cmn |

## Public functions

### get

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
operator fun get(index: Int): T?
```

Returns the presented item at the specified position, notifying Paging of the item access to trigger any loads necessary to fulfill prefetchDistance.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#peek(kotlin.Int)` |   |

### peek

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
fun peek(index: Int): T?
```

Returns the presented item at the specified position, without notifying Paging of the item access that would normally trigger page loads.

| Parameters |
|---|---|
| `index: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Index of the presented item to return, including placeholders. |

| Returns |
|---|---|
| `T?` | The presented item at position `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#peek(kotlin.Int)`, `null` if it is a placeholder |

### refresh

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
fun refresh(): Unit
```

Refresh the data presented by this `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems`.

`https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#refresh()` triggers the creation of a new `https://developer.android.com/reference/kotlin/androidx/paging/PagingData` with a new instance of `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource` to represent an updated snapshot of the backing dataset. If a `https://developer.android.com/reference/kotlin/androidx/paging/RemoteMediator` is set, calling `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#refresh()` will also trigger a call to `https://developer.android.com/reference/kotlin/androidx/paging/RemoteMediator#load(androidx.paging.LoadType,androidx.paging.PagingState)` with `https://developer.android.com/reference/kotlin/androidx/paging/LoadType#REFRESH` to allow `https://developer.android.com/reference/kotlin/androidx/paging/RemoteMediator` to check for updates to the dataset backing `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource`.

Note: This API is intended for UI-driven refresh signals, such as swipe-to-refresh. Invalidation due repository-layer signals, such as DB-updates, should instead use `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource#invalidate()`.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource#invalidate()` |   |

### retry

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
fun retry(): Unit
```

Retry any failed load requests that would result in a `https://developer.android.com/reference/kotlin/androidx/paging/LoadState.Error` update to this `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems`.

Unlike `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#refresh()`, this does not invalidate `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource`, it only retries failed loads within the same generation of `https://developer.android.com/reference/kotlin/androidx/paging/PagingData`.

`https://developer.android.com/reference/kotlin/androidx/paging/LoadState.Error` can be generated from two types of load requests:

- `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource#load(androidx.paging.PagingSource.LoadParams)` returning `https://developer.android.com/reference/kotlin/androidx/paging/PagingSource.LoadResult.Error`

- `https://developer.android.com/reference/kotlin/androidx/paging/RemoteMediator#load(androidx.paging.LoadType,androidx.paging.PagingState)` returning `https://developer.android.com/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.Error`

## Public properties

### itemCount

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
val itemCount: Int
```

The number of items which can be accessed.

### itemSnapshotList

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
val itemSnapshotList: ItemSnapshotList<T>
```

Contains the immutable `https://developer.android.com/reference/kotlin/androidx/paging/ItemSnapshotList` of currently presented items, including any placeholders if they are enabled. Note that similarly to `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#peek(kotlin.Int)` accessing the items in a list will not trigger any loads. Use `https://developer.android.com/reference/kotlin/androidx/paging/compose/LazyPagingItems#get(kotlin.Int)` to achieve such behavior.

### loadState

Cmn Added in [3.2.0](https://developer.android.com/jetpack/androidx/releases/paging#3.2.0)

```
val loadState: CombinedLoadStates
```

A `https://developer.android.com/reference/kotlin/androidx/paging/CombinedLoadStates` object which represents the current loading state.

## Extension functions

### LazyPagingItems.itemContentType

Cmn Artifact: [androidx.paging:paging-compose](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/compose/LazyFoundationExtensions.kt+function:itemContentType)

```
fun <T : Any> LazyPagingItems<T>.itemContentType(
    contentType: ((item) -> Any?)? = null
): (index: Int) -> Any?
```

Returns a factory for the content type of the item.

ContentTypes are generated with the contentType lambda that is passed in. If null is passed in, contentType of all items will default to `null`. If `https://developer.android.com/reference/kotlin/androidx/paging/PagingConfig#enablePlaceholders()` is true, LazyPagingItems may return null items. Null items will automatically default to placeholder contentType.

This factory can be applied to Lazy foundations such as `LazyGridScope.items` or Pagers. Examples:

```kotlin
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.paging.compose.collectAsLazyPagingItems
import androidx.paging.compose.itemContentType
import androidx.paging.compose.itemKey

val lazyPagingItems = pager.collectAsLazyPagingItems()

LazyVerticalGrid(columns = GridCells.Fixed(2)) {
    items(
        count = lazyPagingItems.itemCount,
        key = lazyPagingItems.itemKey { it },
        contentType = lazyPagingItems.itemContentType { "MyPagingItems" },
    ) { index ->
        val item = lazyPagingItems[index]
        PagingItem(item = item)
    }
}
```

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.paging.compose.collectAsLazyPagingItems
import androidx.paging.compose.itemContentType
import androidx.paging.compose.itemKey

val lazyPagingItems = pager.collectAsLazyPagingItems()

LazyColumn {
    stickyHeader(key = "Header", contentType = "My Header") {
        Box(
            modifier = Modifier.padding(bottom = 10.dp).background(Color.Red).fillMaxWidth(),
            contentAlignment = Alignment.Center,
        ) {
            Text(text = "Header", fontSize = 32.sp)
        }
    }
    items(
        count = lazyPagingItems.itemCount,
        key = lazyPagingItems.itemKey { it },
        contentType = lazyPagingItems.itemContentType { "MyPagingItems" },
    ) { index ->
        val item = lazyPagingItems[index]
        PagingItem(item = item)
    }
}
```

| Parameters |
|---|---|
| `contentType: ((item) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)? = null` | a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible. |

### LazyPagingItems.itemKey

Cmn Artifact: [androidx.paging:paging-compose](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/compose/LazyFoundationExtensions.kt+function:itemKey)

```
fun <T : Any> LazyPagingItems<T>.itemKey(key: ((item) -> Any)? = null): (index: Int) -> Any
```

Returns a factory of stable and unique keys representing the item.

Keys are generated with the key lambda that is passed in. If null is passed in, keys will default to a placeholder key. If `https://developer.android.com/reference/kotlin/androidx/paging/PagingConfig#enablePlaceholders()` is true, LazyPagingItems may return null items. Null items will also automatically default to a placeholder key.

This factory can be applied to Lazy foundations such as compose foundation's `LazyGridScope` or Pagers. Examples:

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.PageSize
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.paging.Pager
import androidx.paging.compose.collectAsLazyPagingItems
import androidx.paging.compose.itemKey

val lazyPagingItems = pager.collectAsLazyPagingItems()
val pagerState = rememberPagerState { lazyPagingItems.itemCount }

HorizontalPager(
    modifier = Modifier.fillMaxSize(),
    state = pagerState,
    pageSize = PageSize.Fixed(200.dp),
    key = lazyPagingItems.itemKey { it },
) { index ->
    val item = lazyPagingItems[index]
    PagingItem(item = item)
}
```

```kotlin
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.paging.compose.collectAsLazyPagingItems
import androidx.paging.compose.itemContentType
import androidx.paging.compose.itemKey

val lazyPagingItems = pager.collectAsLazyPagingItems()

LazyVerticalGrid(columns = GridCells.Fixed(2)) {
    items(
        count = lazyPagingItems.itemCount,
        key = lazyPagingItems.itemKey { it },
        contentType = lazyPagingItems.itemContentType { "MyPagingItems" },
    ) { index ->
        val item = lazyPagingItems[index]
        PagingItem(item = item)
    }
}
```

| Parameters |
|---|---|
| `key: ((item) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html)? = null` | a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one. |