Android 12 Developer Preview is here! Try it out, and give us your feedback!

ScrollState

@Stable class ScrollState : ScrollableState
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 Modifier.verticalScroll or Modifier.horizontalScroll

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

Learn how to control the state of Modifier.verticalScroll or Modifier.horizontalScroll:

import androidx.compose.foundation.gestures.scrollBy
import androidx.compose.foundation.gestures.animateScrollBy
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Text
import androidx.compose.runtime.rememberCoroutineScope

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

Summary

Public constructors
<init>(initial: Int)

State of the scroll.

Public methods
suspend Unit
animateScrollTo(value: Int, animationSpec: AnimationSpec<Float> = SpringSpec())

Scroll to position in pixels with animation.

Float

Dispatch scroll delta in pixels avoiding all scroll related mechanisms.

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.

suspend Float
scrollTo(value: Int)

Instantly jump to the given position in pixels.

Inherited extension functions
From androidx.compose.foundation.gestures
suspend Float
ScrollableState.animateScrollBy(value: Float, animationSpec: AnimationSpec<Float> = spring())

Scroll by value pixels with animation.

suspend Float

Jump instantly by value pixels.

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

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

Properties
InteractionSource

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

Boolean

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

Int

maximum bound for value, or Int.MAX_VALUE if still unknown

Int

current scroll position value in pixels

Companion properties
Saver<ScrollState, *>

The default Saver implementation for ScrollState.

Public constructors

<init>

ScrollState(initial: Int)

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 Modifier.verticalScroll or Modifier.horizontalScroll

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

Learn how to control the state of Modifier.verticalScroll or Modifier.horizontalScroll:

import androidx.compose.foundation.gestures.scrollBy
import androidx.compose.foundation.gestures.animateScrollBy
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Text
import androidx.compose.runtime.rememberCoroutineScope

// Create ScrollState to own it and be able to control scroll behaviour of scrollable Row below
val scrollState = rememberScrollState()
val scope = rememberCoroutineScope()
Column {
    Row(Modifier.horizontalScroll(scrollState)) {
        repeat(1000) { index ->
            Square(index)
        }
    }
    // Controls for scrolling
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Scroll")
        Button(
            onClick = {
                scope.launch { scrollState.scrollTo(scrollState.value - 1000) }
            }
        ) {
            Text("< -")
        }
        Button(
            onClick = {
                scope.launch { scrollState.scrollBy(10000f) }
            }
        ) {
            Text("--- >")
        }
    }
    Row(verticalAlignment = Alignment.CenterVertically) {
        Text("Smooth Scroll")
        Button(
            onClick = {
                scope.launch { scrollState.animateScrollTo(scrollState.value - 1000) }
            }
        ) {
            Text("< -")
        }
        Button(
            onClick = {
                scope.launch { scrollState.animateScrollBy(10000f) }
            }
        ) {
            Text("--- >")
        }
    }
}
Parameters
initial: Int value of the scroll

Public methods

animateScrollTo

suspend fun animateScrollTo(
    value: Int,
    animationSpec: AnimationSpec<Float