# scrollable

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/scrollable.modifier#(androidx.compose.ui.Modifier).scrollable(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource)( state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState, orientation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, reverseDirection: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior?, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? )` Configure touch scrolling and flinging for the UI element in a single `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/scrollable.modifier#(androidx.compose.ui.Modifier).scrollable(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,androidx.compose.foundation.OverscrollEffect,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.gestures.BringIntoViewSpec)( state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState, orientation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation, overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect?, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, reverseDirection: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior?, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource?, bringIntoViewSpec: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/BringIntoViewSpec? )` Configure touch scrolling and flinging for the UI element in a single `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation`. | Cmn |

## Functions

### Modifier.scrollable

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/gestures/Scrollable.kt+function:scrollable) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.0.0)

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

Configure touch scrolling and flinging for the UI element in a single `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation`.

Users should update their state themselves using default `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` and its `consumeScrollDelta` callback or by implementing `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` interface manually and reflect their own state in UI when using this component.

`scrollable` is a low-level modifier that handles low-level scrolling input gestures, without other behaviors commonly used for scrollable containers. For building scrollable containers, see `https://developer.android.com/reference/kotlin/androidx/compose/foundation/scrollableArea.modifier#(androidx.compose.ui.Modifier).scrollableArea(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.gestures.BringIntoViewSpec)`. `scrollableArea` clips its content to its bounds, renders overscroll, and adjusts the direction of scroll gestures to ensure that the content moves with the user's gestures. See also `https://developer.android.com/reference/kotlin/androidx/compose/foundation/verticalScroll.modifier#(androidx.compose.ui.Modifier).verticalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/horizontalScroll.modifier#(androidx.compose.ui.Modifier).horizontalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)` for high-level scrollable containers that handle layout and move the content as the user scrolls.

If you don't need to have fling or nested scroll support, but want to make component simply draggable, consider using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/draggable.modifier#(androidx.compose.ui.Modifier).draggable(androidx.compose.foundation.gestures.DraggableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Boolean,kotlin.coroutines.SuspendFunction2,kotlin.coroutines.SuspendFunction2,kotlin.Boolean)`.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.Orientation
import androidx.compose.foundation.gestures.rememberScrollableState
import androidx.compose.foundation.gestures.scrollable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
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.text.TextStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// actual composable state that we will show on UI and update in `Scrollable`
var offset by 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 = offset + 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.roundToInt().toString(), style = TextStyle(fontSize = 32.sp))
}
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` state of the scrollable. Defines how scroll events will be interpreted by the user land logic and contains useful information about ongoing events. |
| `orientation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation` | orientation of the scrolling |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | whether scrolling is enabled |
| `reverseDirection: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior? = null` | logic describing fling behavior when drag has finished with velocity. If `null`, default from `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableDefaults#flingBehavior()` will be used. |
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource` that will be used to emit drag events when this scrollable is being dragged. |

### Modifier.scrollable

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/gestures/Scrollable.kt+function:scrollable) Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.6.0)

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

Configure touch scrolling and flinging for the UI element in a single `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation`.

Users should update their state themselves using default `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` and its `consumeScrollDelta` callback or by implementing `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` interface manually and reflect their own state in UI when using this component.

`scrollable` is a low-level modifier that handles low-level scrolling input gestures, without other behaviors commonly used for scrollable containers. For building scrollable containers, see `https://developer.android.com/reference/kotlin/androidx/compose/foundation/scrollableArea.modifier#(androidx.compose.ui.Modifier).scrollableArea(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.gestures.BringIntoViewSpec)`. `scrollableArea` clips its content to its bounds, renders overscroll, and adjusts the direction of scroll gestures to ensure that the content moves with the user's gestures. See also `https://developer.android.com/reference/kotlin/androidx/compose/foundation/verticalScroll.modifier#(androidx.compose.ui.Modifier).verticalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/horizontalScroll.modifier#(androidx.compose.ui.Modifier).horizontalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)` for high-level scrollable containers that handle layout and move the content as the user scrolls.

If you don't need to have fling or nested scroll support, but want to make component simply draggable, consider using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/draggable.modifier#(androidx.compose.ui.Modifier).draggable(androidx.compose.foundation.gestures.DraggableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Boolean,kotlin.coroutines.SuspendFunction2,kotlin.coroutines.SuspendFunction2,kotlin.Boolean)`.

This overload provides the access to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect` that defines the behavior of the over-scrolling logic. Use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/rememberOverscrollEffect.composable#rememberOverscrollEffect()` to create an instance of the current provided overscroll implementation. Note: compared to other APIs that accept `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/package-summary#(androidx.compose.ui.Modifier).scrollable(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,androidx.compose.foundation.OverscrollEffect,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.gestures.BringIntoViewSpec)` such as `https://developer.android.com/reference/kotlin/androidx/compose/foundation/scrollableArea.modifier#(androidx.compose.ui.Modifier).scrollableArea(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.gestures.BringIntoViewSpec)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/verticalScroll.modifier#(androidx.compose.ui.Modifier).verticalScroll(androidx.compose.foundation.ScrollState,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean)`, `scrollable` does not render the overscroll, it only provides events. Manually add `https://developer.android.com/reference/kotlin/androidx/compose/foundation/overscroll.modifier#(androidx.compose.ui.Modifier).overscroll(androidx.compose.foundation.OverscrollEffect)` to render the overscroll or use other APIs.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.Orientation
import androidx.compose.foundation.gestures.rememberScrollableState
import androidx.compose.foundation.gestures.scrollable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
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.text.TextStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// actual composable state that we will show on UI and update in `Scrollable`
var offset by 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 = offset + 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.roundToInt().toString(), style = TextStyle(fontSize = 32.sp))
}
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableState` state of the scrollable. Defines how scroll events will be interpreted by the user land logic and contains useful information about ongoing events. |
| `orientation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/Orientation` | orientation of the scrolling |
| `overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/overscroll.modifier#(androidx.compose.ui.Modifier).overscroll(androidx.compose.foundation.OverscrollEffect)` modifier. |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | whether scrolling is enabled |
| `reverseDirection: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior? = null` | logic describing fling behavior when drag has finished with velocity. If `null`, default from `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/ScrollableDefaults#flingBehavior()` will be used. |
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource` that will be used to emit drag events when this scrollable is being dragged. |
| `bringIntoViewSpec: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/BringIntoViewSpec? = null` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/package-summary#LocalBringIntoViewSpec()` which by default has a platform-dependent implementation. |