ScrollableState

Artifact: androidx.compose.foundation:foundation

View Source

Added in 1.0.0

Common/AllAndroid/JVM

• Cmn

  interface ScrollableState

Known direct subclasses

CarouselState, LazyGridState, LazyListState, LazyStaggeredGridState, PagerState, PickerState, PickerState, ScalingLazyListState, ScalingLazyListState, ScrollState, TransformingLazyColumnState, TvLazyGridState, TvLazyListState

CarouselState	The state that can be used to control all types of carousels.
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.
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.
TransformingLazyColumnState	A state object that can be hoisted to control and observe scrolling.
TvLazyGridState	This class is deprecated. Use `LazyGridState` instead.
TvLazyListState	This class is deprecated. Use `LazyListState` instead.

Known indirect subclasses

PagerState

PagerState

The state that can be used to control Wear Pagers.

---

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.

See also
animateScrollBy
scrollable

Summary

Public functions
Float	dispatchRawDelta(delta: 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	canScrollBackward Whether this ScrollableState can scroll backward (consume a negative delta).	Cmn
open Boolean	canScrollForward Whether this ScrollableState can scroll forward (consume a positive delta).	Cmn
Boolean	isScrollInProgress Whether this ScrollableState is currently scrolling by gesture, fling or programmatically or not.	Cmn
open Boolean	lastScrolledBackward The value of this property is true under the following scenarios, otherwise it's false.	Cmn
open Boolean	lastScrolledForward The value of this property is true under the following scenarios, otherwise it's false.	Cmn

Extension functions
suspend Float	ScrollableState.animateScrollBy(     value: Float,     animationSpec: AnimationSpec<Float> ) Scroll by value pixels with animation.	Cmn
suspend Float	ScrollableState.scrollBy(value: Float) Jump instantly by value pixels.	Cmn
suspend Unit	ScrollableState.stopScroll(scrollPriority: MutatePriority) Stop and suspend until any ongoing animation, smooth scrolling, fling, or any other scroll occurring via ScrollableState.scroll is terminated.	Cmn

Public functions

dispatchRawDelta

Cmn

Added in 1.0.0

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

Cmn

Added in 1.0.0

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

Cmn

Added in 1.4.0

open val canScrollBackward: Boolean

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

Cmn

Added in 1.4.0

open val canScrollForward: Boolean

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

isScrollInProgress

Cmn

Added in 1.0.0

val isScrollInProgress: Boolean

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

lastScrolledBackward

Cmn

Added in 1.7.0

open val lastScrolledBackward: Boolean

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

• This ScrollableState is currently scrolling backward.

• This ScrollableState was scrolling backward in its last scroll action.

lastScrolledForward

Cmn

Added in 1.7.0

open val lastScrolledForward: Boolean

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

• This ScrollableState is currently scrolling forward.

• This ScrollableState was scrolling forward in its last scroll action.

Extension functions

animateScrollBy

Cmn

Artifact: androidx.compose.foundation:foundation

View Source

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

scrollBy

Cmn

Artifact: androidx.compose.foundation:foundation

View Source

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

stopScroll

Cmn

Artifact: androidx.compose.foundation:foundation

View Source

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