Google is committed to advancing racial equity for Black communities. See how.

ScrollState

@Stable class ScrollState
kotlin.Any
   ↳ androidx.compose.foundation.ScrollState

State of the scroll. Allows the developer to change the scroll position or get current state by calling methods on this object. To be hosted and passed to ScrollableRow, ScrollableColumn, Modifier.verticalScroll or Modifier.horizontalScroll

To create and automatically remember ScrollState with default parameters use rememberScrollState.

Learn how to control ScrollableColumn or ScrollableRow:

import androidx.compose.foundation.ScrollableRow
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Text

// Create ScrollState to own it and be able to control scroll behaviour of ScrollableRow below
val scrollState = rememberScrollState()
Column {
    ScrollableRow(scrollState = scrollState) {
        repeat(1000) { index ->
            Square(index)
        }
    }
    // Controls for scrolling
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Scroll")
        Button(onClick = { scrollState.scrollTo(scrollState.value - 1000) }) {
            Text("< -")
        }
        Button(onClick = { scrollState.scrollBy(10000f) }) {
            Text("--- >")
        }
    }
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Smooth Scroll")
        Button(onClick = { scrollState.smoothScrollTo(scrollState.value - 1000) }) {
            Text("< -")
        }
        Button(onClick = { scrollState.smoothScrollBy(10000f) }) {
            Text("--- >")
        }
    }
}

Summary

Public constructors
<init>(initial: Float, flingConfig: FlingConfig, animationClock: AnimationClockObservable, interactionState: InteractionState? = null)

State of the scroll.

Public methods
Unit
scrollBy(value: Float)

Instantly jump by some amount of pixels

Unit
scrollTo(value: Float)

Instantly jump to position in pixels

Unit
smoothScrollBy(value: Float, spec: AnimationSpec<Float> = SpringSpec(), onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> })

Smooth scroll by some amount of pixels

Unit
smoothScrollTo(value: Float, spec: AnimationSpec<Float> = SpringSpec(), onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> })

Smooth scroll to position in pixels

Unit

Stop any ongoing animation, smooth scrolling or fling occurring on this ScrollState

Companion functions
Saver<ScrollState, *>
Saver(flingConfig: FlingConfig, animationClock: AnimationClockObservable, interactionState: InteractionState?)

The default Saver implementation for ScrollState.

Properties
Boolean

whether this ScrollState is currently animating/flinging

Float

maximum bound for value, or Float.POSITIVE_INFINITY if still unknown

Float

current scroll position value in pixels

Public constructors

<init>

ScrollState(
    initial: Float,
    flingConfig: FlingConfig,
    animationClock: AnimationClockObservable,
    interactionState: InteractionState? = null)

State of the scroll. Allows the developer to change the scroll position or get current state by calling methods on this object. To be hosted and passed to ScrollableRow, ScrollableColumn, Modifier.verticalScroll or Modifier.horizontalScroll

To create and automatically remember ScrollState with default parameters use rememberScrollState.

Learn how to control ScrollableColumn or ScrollableRow:

import androidx.compose.foundation.ScrollableRow
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Text

// Create ScrollState to own it and be able to control scroll behaviour of ScrollableRow below
val scrollState = rememberScrollState()
Column {
    ScrollableRow(scrollState = scrollState) {
        repeat(1000) { index ->
            Square(index)
        }
    }
    // Controls for scrolling
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Scroll")
        Button(onClick = { scrollState.scrollTo(scrollState.value - 1000) }) {
            Text("< -")
        }
        Button(onClick = { scrollState.scrollBy(10000f) }) {
            Text("--- >")
        }
    }
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Smooth Scroll")
        Button(onClick = { scrollState.smoothScrollTo(scrollState.value - 1000) }) {
            Text("< -")
        }
        Button(onClick = { scrollState.smoothScrollBy(10000f) }) {
            Text("--- >")
        }
    }
}
Parameters
initial: Float value of the scroll
flingConfig: FlingConfig fling configuration to use for flinging
animationClock: AnimationClockObservable animation clock to run flinging and smooth scrolling on
interactionState: InteractionState? = null InteractionState that will be updated when the element with this state is being scrolled by dragging, using Interaction.Dragged. If you want to know whether the fling (or smooth scroll) is in progress, use ScrollState.isAnimationRunning.

Public methods

scrollBy

fun scrollBy(value: Float): Unit

Instantly jump by some amount of pixels

Parameters
value: Float delta in pixels to jump by, total value will be coerced to 0..maxPosition

scrollTo

fun scrollTo(value: Float): Unit

Instantly jump to position in pixels

Parameters
value: Float target value in pixels to jump to, value will be coerced to 0..maxPosition

smoothScrollBy

fun smoothScrollBy(
    value: Float,
    spec: AnimationSpec<Float> = SpringSpec(),
    onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> }
): Unit

Smooth scroll by some amount of pixels

Parameters
value: Float delta in pixels to scroll by, total value will be coerced to 0..maxPosition
spec: AnimationSpec<Float> = SpringSpec() animation curve for smooth scroll animation
onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> } callback to be invoked when smooth scroll has finished

smoothScrollTo

fun smoothScrollTo(
    value: Float,
    spec: AnimationSpec<Float> = SpringSpec(),
    onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> }
): Unit

Smooth scroll to position in pixels

Parameters
value: Float target value in pixels to smooth scroll to, value will be coerced to 0..maxPosition
spec: AnimationSpec<Float> = SpringSpec() animation curve for smooth scroll animation
onEnd: (endReason: AnimationEndReason, finishValue: Float) -> Unit = { _, _ -> } callback to be invoked when smooth scroll has finished

stopAnimation

fun stopAnimation(): Unit

Stop any ongoing animation, smooth scrolling or fling occurring on this ScrollState

Properties

isAnimationRunning

val isAnimationRunning: Boolean

whether this ScrollState is currently animating/flinging

maxValue

var maxValue: Float

maximum bound for value, or Float.POSITIVE_INFINITY if still unknown

value

var value: Float

current scroll position value in pixels

Companion functions

Saver

fun Saver(
    flingConfig: FlingConfig,
    animationClock: AnimationClockObservable,
    interactionState: InteractionState?
): Saver<ScrollState, *>

The default Saver implementation for ScrollState.