androidx.compose.foundation.lazy

In this page, you'll find documentation for types, properties, and functions available in the androidx.compose.foundation.lazy package such as LazyColumn, LazyRow, and rememberLazyListState.

If you're looking for guidance instead, check out the Lists in Compose guide.

Interfaces

LazyItemScope

Receiver scope being used by the item content parameter of LazyColumn/Row.
Cmn
LazyListItemInfo

Contains useful information about an individual item in lazy lists like LazyColumn or LazyRow.
Cmn
LazyListLayoutInfo

Contains useful information about the currently displayed layout state of lazy lists like LazyColumn or LazyRow.
Cmn
LazyListPrefetchResultScope

A scope for LazyListPrefetchScope.schedulePrefetch callbacks.
Cmn
LazyListPrefetchScope

Scope for callbacks in LazyListPrefetchStrategy which allows prefetches to be requested.
Cmn
LazyListPrefetchStrategy

Implementations of this interface control which indices of a LazyList should be prefetched (precomposed and premeasured during idle time) as the user interacts with it.
Cmn
LazyListScope

Receiver scope which is used by LazyColumn and LazyRow.
Cmn

Classes

LazyListState

A state object that can be hoisted to control and observe scrolling.
Cmn

Annotations

LazyScopeMarker

DSL marker used to distinguish between lazy layout scope and the item scope.
Cmn

Composables

LazyColumn

The vertically scrolling list that only composes and lays out the currently visible items.
Cmn
LazyRow

The horizontally scrolling list that only composes and lays out the currently visible items.
Cmn
rememberLazyListState

Creates a LazyListState that is remembered across compositions.
Cmn

Top-level functions summary

LazyLayoutScrollScope

An implementation of LazyLayoutScrollScope that can be used with LazyLists.
Cmn
LazyListPrefetchStrategy

Creates an instance of the default LazyListPrefetchStrategy, allowing for customization of the nested prefetch count.
Cmn

Extension functions summary

inline Unit
<T : Any?> LazyListScope.items(
    items: Array<T>,
    noinline key: ((item) -> Any)?,
    noinline contentType: (item) -> Any?,
    crossinline itemContent: @Composable LazyItemScope.(item) -> Unit
)

Adds an array of items.
Cmn
inline Unit
<T : Any?> LazyListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)?,
    noinline contentType: (item) -> Any?,
    crossinline itemContent: @Composable LazyItemScope.(item) -> Unit
)

Adds a list of items.
Cmn
inline Unit
<T : Any?> LazyListScope.itemsIndexed(
    items: Array<T>,
    noinline key: ((index: Int, item) -> Any)?,
    crossinline contentType: (index: Int, item) -> Any?,
    crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit
)

Adds an array of items where the content of an item is aware of its index.
Cmn
inline Unit
<T : Any?> LazyListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)?,
    crossinline contentType: (index: Int, item) -> Any?,
    crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit
)

Adds a list of items where the content of an item is aware of its index.
Cmn

Top-level functions

LazyLayoutScrollScope

Cmn 
fun LazyLayoutScrollScope(state: LazyListState, scrollScope: ScrollScope): LazyLayoutScrollScope

An implementation of LazyLayoutScrollScope that can be used with LazyLists. Please refer to the sample to learn how to use this API.

import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyLayoutScrollScope
import androidx.compose.foundation.lazy.LazyListState
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.layout.LazyLayoutScrollScope
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.State
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

suspend fun LazyListState.customScroll(block: suspend LazyLayoutScrollScope.() -> Unit) =
    scroll {
        block.invoke(LazyLayoutScrollScope(this@customScroll, this))
    }
val itemsList = (0..100).toList()
val state = rememberLazyListState()
val scope = rememberCoroutineScope()

Column(Modifier.verticalScroll(rememberScrollState())) {
    Button(
        onClick = {
            scope.launch {
                state.customScroll {
                    snapToItem(40, 0) // teleport to item 40
                    val distance = calculateDistanceTo(50).toFloat()
                    var previousValue = 0f
                    androidx.compose.animation.core.animate(
                        0f,
                        distance,
                        animationSpec = tween(5_000),
                    ) { currentValue, _ ->
                        previousValue += scrollBy(currentValue - previousValue)
                    }
                }
            }
        }
    ) {
        Text("Scroll To Item 50")
    }
    LazyRow(state = state) {
        items(itemsList) {
            Box(Modifier.padding(2.dp).background(Color.Red).size(45.dp)) {
                Text(it.toString())
            }
        }
    }
}
Parameters
state: LazyListState

The LazyListState associated with the layout where this custom scroll should be performed.
scrollScope: ScrollScope

The base ScrollScope where the scroll session was created.
Returns
LazyLayoutScrollScope

An implementation of LazyLayoutScrollScope that works with LazyRow and LazyColumn.

LazyListPrefetchStrategy

Cmn 
@ExperimentalFoundationApi
fun LazyListPrefetchStrategy(nestedPrefetchItemCount: Int = 2): LazyListPrefetchStrategy

Creates an instance of the default LazyListPrefetchStrategy, allowing for customization of the nested prefetch count.

Parameters
nestedPrefetchItemCount: Int = 2

specifies how many inner items should be prefetched when this LazyList is nested inside another LazyLayout. For example, if this is the state for a horizontal LazyList nested in a vertical LazyList, you might want to set this to the number of items that will be visible when this list is scrolled into view. If automatic nested prefetch is enabled, this value will be used as the initial count and the strategy will adapt the count automatically.

Extension functions

LazyListScope.items

Cmn 
inline fun <T : Any?> LazyListScope.items(
    items: Array<T>,
    noinline key: ((item) -> Any)? = null,
    noinline contentType: (item) -> Any? = { null },
    crossinline itemContent: @Composable LazyItemScope.(item) -> Unit
): Unit

Adds an array of items.

Parameters
items: Array<T>

the data array
noinline key: ((item) -> Any)? = 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. If null is passed the position in the list will represent the key. 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. This can be overridden by calling 'requestScrollToItem' on the 'LazyListState'.
noinline contentType: (item) -> Any? = { 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.
crossinline itemContent: @Composable LazyItemScope.(item) -> Unit

the content displayed by a single item

LazyListScope.items

Cmn 
inline fun <T : Any?> LazyListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)? = null,
    noinline contentType: (item) -> Any? = { null },
    crossinline itemContent: @Composable LazyItemScope.(item) -> Unit
): Unit

Adds a list of items.

Parameters
items: List<T>

the data list
noinline key: ((item) -> Any)? = 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. If null is passed the position in the list will represent the key. 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. This can be overridden by calling 'requestScrollToItem' on the 'LazyListState'.
noinline contentType: (item) -> Any? = { 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.
crossinline itemContent: @Composable LazyItemScope.(item) -> Unit

the content displayed by a single item

LazyListScope.itemsIndexed

Cmn 
inline fun <T : Any?> LazyListScope.itemsIndexed(
    items: Array<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline contentType: (index: Int, item) -> Any? = { _, _ -> null },
    crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit
): Unit

Adds an array of items where the content of an item is aware of its index.

Parameters
items: Array<T>

the data array
noinline key: ((index: Int, item) -> Any)? = 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. If null is passed the position in the list will represent the key. 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. This can be overridden by calling 'requestScrollToItem' on the 'LazyListState'.
crossinline contentType: (index: Int, item) -> Any? = { _, _ -> 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.
crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit

the content displayed by a single item

LazyListScope.itemsIndexed

Cmn 
inline fun <T : Any?> LazyListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline contentType: (index: Int, item) -> Any? = { _, _ -> null },
    crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit
): Unit

Adds a list of items where the content of an item is aware of its index.

Parameters
items: List<T>

the data list
noinline key: ((index: Int, item) -> Any)? = 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. If null is passed the position in the list will represent the key. 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. This can be overridden by calling 'requestScrollToItem' on the 'LazyListState'.
crossinline contentType: (index: Int, item) -> Any? = { _, _ -> 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.
crossinline itemContent: @Composable LazyItemScope.(index: Int, item) -> Unit

the content displayed by a single item