scrollable

Modifier in Compose Foundation

Configure touch scrolling and flinging for the UI element in a single [Orientation].

Users should update their state themselves using default [ScrollableState] and its consumeScrollDelta callback or by implementing [ScrollableState] interface manually and reflect their own state in UI when using this component.

If you don't need to have fling or nested scroll support, but want to make component simply draggable, consider using [draggable].

Last updated: 2024-10-14 12:17

Installation

dependencies {
   implementation("androidx.compose.foundation:foundation:1.8.0-alpha03")
}

Overloads

@Stable
fun Modifier.scrollable(
    state: ScrollableState,
    orientation: Orientation,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    flingBehavior: FlingBehavior? = null,
    interactionSource: MutableInteractionSource? = null
): Modifier

Parameters

name	description
state	[ScrollableState] state of the scrollable. Defines how scroll events will be interpreted by the user land logic and contains useful information about on-going events.
orientation	orientation of the scrolling
enabled	whether or not scrolling in enabled
reverseDirection	reverse the direction of the scroll, so top to bottom scroll will behave like bottom to top and left to right will behave like right to left.
flingBehavior	logic describing fling behavior when drag has finished with velocity. If null, default from [ScrollableDefaults.flingBehavior] will be used.
interactionSource	[MutableInteractionSource] that will be used to emit drag events when this scrollable is being dragged.

@Stable
fun Modifier.scrollable(
    state: ScrollableState,
    orientation: Orientation,
    overscrollEffect: OverscrollEffect?,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    flingBehavior: FlingBehavior? = null,
    interactionSource: MutableInteractionSource? = null,
    bringIntoViewSpec: BringIntoViewSpec? = null
)

Parameters

name	description
state	[ScrollableState] state of the scrollable. Defines how scroll events will be interpreted by the user land logic and contains useful information about on-going events.
orientation	orientation of the scrolling
overscrollEffect	effect to which the deltas will be fed when the scrollable have some scrolling delta left. Pass null for no overscroll. If you pass an effect you should also apply [androidx.compose.foundation.overscroll] modifier.
enabled	whether or not scrolling in enabled
reverseDirection	reverse the direction of the scroll, so top to bottom scroll will behave like bottom to top and left to right will behave like right to left.
flingBehavior	logic describing fling behavior when drag has finished with velocity. If null, default from [ScrollableDefaults.flingBehavior] will be used.
interactionSource	[MutableInteractionSource] that will be used to emit drag events when this scrollable is being dragged.
bringIntoViewSpec	The configuration that this scrollable should use to perform scrolling when scroll requests are received from the focus system. If null is provided the system will use the behavior provided by [LocalBringIntoViewSpec] which by default has a platform dependent implementation.

Code Example

ScrollableSample

@Composable
fun ScrollableSample() {
    // actual composable state that we will show on UI and update in `Scrollable`
    val offset = remember { mutableStateOf(0f) }
    Box(
        Modifier.size(150.dp)
            .scrollable(
                orientation = Orientation.Vertical,
                // state for Scrollable, describes how consume scroll amount
                state =
                    rememberScrollableState { delta ->
                        // use the scroll data and indicate how much this element consumed.
                        // unconsumed deltas will be propagated to nested scrollables (if present)
                        offset.value = offset.value + delta // update the state
                        delta // indicate that we consumed all the pixels available
                    }
            )
            .background(Color.LightGray),
        contentAlignment = Alignment.Center
    ) {
        // Modifier.scrollable is not opinionated about its children's layouts. It will however
        // promote nested scrolling capabilities if those children also use the modifier.
        // The modifier will not change any layouts so one must handle any desired changes through
        // the delta values in the scrollable state
        Text(offset.value.roundToInt().toString(), style = TextStyle(fontSize = 32.sp))
    }
}