ScrollState

Kotlin |Java

@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.Text
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState

// 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)` 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	`stopAnimation()` Stop any ongoing animation, smooth scrolling or fling occurring on this ScrollState

Companion functions
Saver<ScrollState, *>	`Saver(flingConfig: FlingConfig, animationClock: AnimationClockObservable)` The default Saver implementation for ScrollState.

Properties
Boolean	`isAnimationRunning` whether this ScrollState is currently animating/flinging
Float	`maxValue` maximum bound for value, or Float.POSITIVE_INFINITY if still unknown
Float	`value` current scroll position value in pixels

Public constructors

<init>

ScrollState(
    initial: Float, 
    flingConfig: FlingConfig, 
    animationClock: AnimationClockObservable)

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.Text
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState

// 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

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
): Saver<ScrollState, *>

The default Saver implementation for ScrollState.