LazyStaggeredGridState


Hoisted state object controlling LazyVerticalStaggeredGrid or LazyHorizontalStaggeredGrid. In most cases, it should be created via rememberLazyStaggeredGridState.

Summary

Public companion properties

Saver<LazyStaggeredGridStateAny>

The default implementation of Saver for LazyStaggeredGridState

Cmn

Public constructors

LazyStaggeredGridState(
    initialFirstVisibleItemIndex: Int,
    initialFirstVisibleItemOffset: Int
)
Cmn

Public functions

suspend Unit
animateScrollToItem(index: Int, scrollOffset: Int)

Animate (smooth scroll) to the given item.

Cmn
open Float

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

Cmn
Unit
requestScrollToItem(index: @IntRange(from = 0) Int, scrollOffset: Int)

Requests the item at index to be at the start of the viewport during the next remeasure, offset by scrollOffset, and schedules a remeasure.

Cmn
open suspend Unit
scroll(scrollPriority: MutatePriority, block: suspend ScrollScope.() -> Unit)

Call this function to take control of scrolling and gain the ability to send scroll events via ScrollScope.scrollBy.

Cmn
suspend Unit
scrollToItem(index: Int, scrollOffset: Int)

Instantly brings the item at index to the top of layout viewport, offset by scrollOffset pixels.

Cmn

Public properties

open Boolean

Whether this ScrollableState can scroll backward (consume a negative delta).

Cmn
open Boolean

Whether this ScrollableState can scroll forward (consume a positive delta).

Cmn
Int

Index of the first visible item across all staggered grid lanes.

Cmn
Int

Current offset of the item with firstVisibleItemIndex relative to the container start.

Cmn
InteractionSource

InteractionSource that will be used to dispatch drag events when this list is being dragged.

Cmn
open Boolean

Whether this scrollableState is currently scrolling by gesture, fling or programmatically or not.

Cmn
open Boolean

The value of this property is true under the following scenarios, otherwise it's false.

Cmn
open Boolean

The value of this property is true under the following scenarios, otherwise it's false.

Cmn
LazyStaggeredGridLayoutInfo

Layout information calculated during last layout pass, with information about currently visible items and container parameters.

Cmn

Public companion properties

Saver

val SaverSaver<LazyStaggeredGridStateAny>

The default implementation of Saver for LazyStaggeredGridState

Public constructors

LazyStaggeredGridState

LazyStaggeredGridState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemOffset: Int = 0
)
Parameters
initialFirstVisibleItemIndex: Int = 0

initial value for firstVisibleItemIndex

initialFirstVisibleItemOffset: Int = 0

initial value for firstVisibleItemScrollOffset

Public functions

animateScrollToItem

suspend fun animateScrollToItem(index: Int, scrollOffset: Int = 0): Unit

Animate (smooth scroll) to the given item.

Parameters
index: Int

the index to which to scroll. MUST NOT be negative.

scrollOffset: Int = 0

the offset that the item should end up after the scroll. Note that positive offset refers to forward scroll, so in a top-to-bottom list, positive offset will scroll the item further upward (taking it partly offscreen).

dispatchRawDelta

open fun dispatchRawDelta(delta: Float): Float

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

NOTE: unlike scroll, dispatching any delta with this method won't trigger nested scroll, won't stop ongoing scroll/drag animation and will bypass scrolling of any priority. This method will also ignore reverseDirection and other parameters set in scrollable.

This method is used internally for nested scrolling dispatch and other low level operations, allowing implementers of ScrollableState influence the consumption as suits them. Manually dispatching delta via this method will likely result in a bad user experience, you must prefer scroll method over this one.

Parameters
delta: Float

amount of scroll dispatched in the nested scroll process

Returns
Float

the amount of delta consumed

requestScrollToItem

fun requestScrollToItem(index: @IntRange(from = 0) Int, scrollOffset: Int = 0): Unit

Requests the item at index to be at the start of the viewport during the next remeasure, offset by scrollOffset, and schedules a remeasure.

The scroll position will be updated to the requested position rather than maintain the index based on the first visible item key (when a data set change will also be applied during the next remeasure), but only for the next remeasure.

Any scroll in progress will be cancelled.

Parameters
index: @IntRange(from = 0) Int

the index to which to scroll. Must be non-negative.

scrollOffset: Int = 0

the offset that the item should end up after the scroll. Note that positive offset refers to forward scroll, so in a top-to-bottom list, positive offset will scroll the item further upward (taking it partly offscreen).

scroll

open suspend fun scroll(scrollPriority: MutatePriority, block: suspend ScrollScope.() -> Unit): Unit

Call this function to take control of scrolling and gain the ability to send scroll events via ScrollScope.scrollBy. All actions that change the logical scroll position must be performed within a scroll block (even if they don't call any other methods on this object) in order to guarantee that mutual exclusion is enforced.

If scroll is called from elsewhere, this will be canceled.

scrollToItem

suspend fun scrollToItem(index: Int, scrollOffset: Int = 0): Unit

Instantly brings the item at index to the top of layout viewport, offset by scrollOffset pixels.

Parameters
index: Int

the index to which to scroll. MUST NOT be negative.

scrollOffset: Int = 0

the offset where the item should end up after the scroll. Note that positive offset refers to forward scroll, so in a reversed list, positive offset will scroll the item further upward (taking it partly offscreen).

Public properties

canScrollBackward

open val canScrollBackwardBoolean

Whether this ScrollableState can scroll backward (consume a negative delta). This is typically false if the scroll position is equal to its minimum value, and true otherwise.

Note that true here does not imply that delta will be consumed - the ScrollableState may decide not to handle the incoming delta (such as if it is already being scrolled separately). Additionally, for backwards compatibility with previous versions of ScrollableState this value defaults to true.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.material.Icon
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.KeyboardArrowDown
import androidx.compose.material.icons.filled.KeyboardArrowUp
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.graphicsLayer

val state = rememberLazyListState()
Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
    Icon(
        Icons.Filled.KeyboardArrowUp,
        null,
        Modifier.graphicsLayer {
            // Hide the icon if we cannot scroll backward (we are the start of the list)
            // We use graphicsLayer here to control the alpha so that we only redraw when this
            // value changes, instead of recomposing
            alpha = if (state.canScrollBackward) 1f else 0f
        },
        Color.Red
    )
    val items = (1..100).toList()
    LazyColumn(Modifier.weight(1f).fillMaxWidth(), state) {
        items(items) { Text("Item is $it") }
    }
    Icon(
        Icons.Filled.KeyboardArrowDown,
        null,
        Modifier.graphicsLayer {
            // Hide the icon if we cannot scroll forward (we are the end of the list)
            // We use graphicsLayer here to control the alpha so that we only redraw when this
            // value changes, instead of recomposing
            alpha = if (state.canScrollForward) 1f else 0f
        },
        Color.Red
    )
}

canScrollForward

open val canScrollForwardBoolean

Whether this ScrollableState can scroll forward (consume a positive delta). This is typically false if the scroll position is equal to its maximum value, and true otherwise.

Note that true here does not imply that delta will be consumed - the ScrollableState may decide not to handle the incoming delta (such as if it is already being scrolled separately). Additionally, for backwards compatibility with previous versions of ScrollableState this value defaults to true.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.material.Icon
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.KeyboardArrowDown
import androidx.compose.material.icons.filled.KeyboardArrowUp
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.graphicsLayer

val state = rememberLazyListState()
Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
    Icon(
        Icons.Filled.KeyboardArrowUp,
        null,
        Modifier.graphicsLayer {
            // Hide the icon if we cannot scroll backward (we are the start of the list)
            // We use graphicsLayer here to control the alpha so that we only redraw when this
            // value changes, instead of recomposing
            alpha = if (state.canScrollBackward) 1f else 0f
        },
        Color.Red
    )
    val items = (1..100).toList()
    LazyColumn(Modifier.weight(1f).fillMaxWidth(), state) {
        items(items) { Text("Item is $it") }
    }
    Icon(
        Icons.Filled.KeyboardArrowDown,
        null,
        Modifier.graphicsLayer {
            // Hide the icon if we cannot scroll forward (we are the end of the list)
            // We use graphicsLayer here to control the alpha so that we only redraw when this
            // value changes, instead of recomposing
            alpha = if (state.canScrollForward) 1f else 0f
        },
        Color.Red
    )
}

firstVisibleItemIndex

val firstVisibleItemIndexInt

Index of the first visible item across all staggered grid lanes. This does not include items in the content padding region. For the first visible item that includes items in the content padding please use LazyStaggeredGridLayoutInfo.visibleItemsInfo.

This property is observable and when use it in composable function it will be recomposed on each scroll, potentially causing performance issues.

firstVisibleItemScrollOffset

val firstVisibleItemScrollOffsetInt

Current offset of the item with firstVisibleItemIndex relative to the container start.

This property is observable and when use it in composable function it will be recomposed on each scroll, potentially causing performance issues.

interactionSource

val interactionSourceInteractionSource

InteractionSource that will be used to dispatch drag events when this list is being dragged. If you want to know whether the fling (or animated scroll) is in progress, use isScrollInProgress.

isScrollInProgress

open val isScrollInProgressBoolean

Whether this scrollableState is currently scrolling by gesture, fling or programmatically or not.

lastScrolledBackward

open val lastScrolledBackwardBoolean

The value of this property is true under the following scenarios, otherwise it's false.

lastScrolledForward

open val lastScrolledForwardBoolean

The value of this property is true under the following scenarios, otherwise it's false.

layoutInfo

val layoutInfoLazyStaggeredGridLayoutInfo

Layout information calculated during last layout pass, with information about currently visible items and container parameters.

This property is observable and when use it in composable function it will be recomposed on each scroll, potentially causing performance issues.