ScrollableState

Known direct subclasses
LazyGridState

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

LazyListState

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

LazyStaggeredGridState

Hoisted state object controlling LazyVerticalStaggeredGrid or LazyHorizontalStaggeredGrid.

PagerState

The state that can be used to control VerticalPager and HorizontalPager

PickerState

A state object that can be hoisted to observe item selection.

ScalingLazyListState

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

ScalingLazyListState

This class is deprecated. Was moved to androidx.wear.compose.foundation.lazy package.

ScrollState

State of the scroll.

TvLazyGridState

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

TvLazyListState

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


An object representing something that can be scrolled. This interface is implemented by states of scrollable containers such as androidx.compose.foundation.lazy.LazyListState or androidx.compose.foundation.ScrollState in order to provide low-level scrolling control via scroll, as well as allowing for higher-level scrolling functions like animateScrollBy to be implemented as extension functions on ScrollableState.

Subclasses may also have their own methods that are specific to their interaction paradigm, such as androidx.compose.foundation.lazy.LazyListState.scrollToItem.

Summary

Public functions

Float

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

Cmn
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

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
Boolean

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

Cmn

Extension functions

suspend Float
ScrollableState.animateScrollBy(
    value: Float,
    animationSpec: AnimationSpec<Float>
)

Scroll by value pixels with animation.

Cmn
suspend Float

Jump instantly by value pixels.

Cmn
suspend Unit

Stop and suspend until any ongoing animation, smooth scrolling, fling, or any other scroll occurring via ScrollableState.scroll is terminated.

Cmn

Public functions

dispatchRawDelta

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

scroll

suspend fun scroll(
    scrollPriority: MutatePriority = MutatePriority.Default,
    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 with the scrollPriority higher or equal to ongoing scroll, ongoing scroll will be canceled.

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

isScrollInProgress

val isScrollInProgressBoolean

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

Extension functions

animateScrollBy

suspend fun ScrollableState.animateScrollBy(
    value: Float,
    animationSpec: AnimationSpec<Float> = spring()
): Float

Scroll by value pixels with animation.

Cancels the currently running scroll, if any, and suspends until the cancellation is complete.

Parameters
value: Float

number of pixels to scroll by

animationSpec: AnimationSpec<Float> = spring()

AnimationSpec to be used for this scrolling

Returns
Float

the amount of scroll consumed

suspend fun ScrollableState.scrollBy(value: Float): Float

Jump instantly by value pixels.

Cancels the currently running scroll, if any, and suspends until the cancellation is complete.

Parameters
value: Float

number of pixels to scroll by

Returns
Float

the amount of scroll consumed

See also
animateScrollBy

for an animated version

suspend fun ScrollableState.stopScroll(
    scrollPriority: MutatePriority = MutatePriority.Default
): Unit

Stop and suspend until any ongoing animation, smooth scrolling, fling, or any other scroll occurring via ScrollableState.scroll is terminated.

Parameters
scrollPriority: MutatePriority = MutatePriority.Default

scrolls that run with this priority or lower will be stopped