public final class ListState implements ScrollableState

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

In most cases, this will be created via rememberListState.

Summary

Nested types
public static class ListState.Companion

Public constructors
ListState(int firstVisibleItemIndex, int firstVisibleItemScrollOffset)

Public methods
final void
animateScrollToItem(@IntRange(from = 0) int index, int scrollOffset)

Animate (smooth scroll) to the given item.
float
dispatchRawDelta(float delta)
boolean
boolean
final int

The index of the first item that is visible within the scrollable viewport area not including items in the content padding region.
final int

The scroll offset of the first visible item.
final @NonNull InteractionSource

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

The object of ListLayoutInfo calculated during the last layout pass.
boolean
void
scroll(
    @NonNull MutatePriority scrollPriority,
    @NonNull SuspendFunction1<@NonNull ScrollScope, Unit> block
)
final void
scrollToItem(@IntRange(from = 0) int index, int scrollOffset)

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

Inherited methods
From androidx.compose.foundation.gestures.ScrollableState
boolean
boolean
ScrollIndicatorState

Public constructors

ListState

Added in 1.0.0-alpha01
public ListState(int firstVisibleItemIndex, int firstVisibleItemScrollOffset)
Parameters
int firstVisibleItemIndex

the initial value for ListState.firstVisibleItemIndex
int firstVisibleItemScrollOffset

the initial value for ListState.firstVisibleItemScrollOffset

Public methods

animateScrollToItem

Added in 1.0.0-alpha01
public final void animateScrollToItem(@IntRange(from = 0) int index, int scrollOffset)

Animate (smooth scroll) to the given item.

Parameters
@IntRange(from = 0) int index

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

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

Added in 1.0.0-alpha01
public float dispatchRawDelta(float delta)

getCanScrollBackward

public boolean getCanScrollBackward()

getCanScrollForward

public boolean getCanScrollForward()

getFirstVisibleItemIndex

Added in 1.0.0-alpha01
@FrequentlyChangingValue
public final int getFirstVisibleItemIndex()

The index of the first item that is visible within the scrollable viewport area not including items in the content padding region. For the first visible item that includes items in the content padding please use ListLayoutInfo.visibleItemsInfo.

Note that this property is observable and if you use it in the composable function it will be recomposed on every change causing potential performance issues.

getFirstVisibleItemScrollOffset

Added in 1.0.0-alpha01
@FrequentlyChangingValue
public final int getFirstVisibleItemScrollOffset()

The scroll offset of the first visible item. Scrolling forward is positive - i.e., the amount that the item is offset backwards.

Note that this property is observable and if you use it in the composable function it will be recomposed on every scroll causing potential performance issues.

getInteractionSource

Added in 1.0.0-alpha01
public final @NonNull InteractionSource getInteractionSource()

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.

getLayoutInfo

Added in 1.0.0-alpha01
@FrequentlyChangingValue
public final @NonNull ListLayoutInfo getLayoutInfo()

The object of ListLayoutInfo calculated during the last layout pass. For example, you can use it to calculate what items are currently visible.

Note that this property is observable and is updated after every scroll or remeasure. If you use it in the composable function it will be recomposed on every change causing potential performance issues including infinity recomposition loop. Therefore, avoid using it in the composition.

If you want to run some side effects like sending an analytics event or updating a state based on this value consider using "snapshotFlow":

isScrollInProgress

Added in 1.0.0-alpha01
public boolean isScrollInProgress()

scroll

Added in 1.0.0-alpha01
public void scroll(
    @NonNull MutatePriority scrollPriority,
    @NonNull SuspendFunction1<@NonNull ScrollScope, Unit> block
)

scrollToItem

Added in 1.0.0-alpha01
public final void scrollToItem(@IntRange(from = 0) int index, int scrollOffset)

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

Parameters
@IntRange(from = 0) int index

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

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).