Compose Modifier
Common
```kotlin
fun Modifier.nestedScroll(
connection: NestedScrollConnection,
dispatcher: NestedScrollDispatcher? = null,
): Modifier
```
Modify element to make it participate in the nested scrolling hierarchy.
There are two ways to participate in the nested scroll: as a scrolling child by dispatching
scrolling events via `NestedScrollDispatcher` to the nested scroll chain; and as a member of
nested scroll chain by providing `NestedScrollConnection`, which will be called when another
nested scrolling child below dispatches scrolling events.
It's mandatory to participate as a `NestedScrollConnection` in the chain, but dispatching
scrolling events is optional since there are cases where an element wants to participate in
nested scrolling without being directly scrollable.
Here's the collapsing toolbar example that participates in a chain, but doesn't dispatch:
On the other side, dispatch via `NestedScrollDispatcher` is optional. It's needed if a component
is able to receive and react to the drag/fling events and you want this components to be able to
notify parents when scroll occurs, resulting in better overall coordination.
Here's the example of the component that is draggable and dispatches nested scroll to participate
in the nested scroll chain:
**Note:** It is recommended to reuse `NestedScrollConnection` and `NestedScrollDispatcher`
objects between recompositions since different object will cause nested scroll graph to be
recalculated unnecessary.
There are 4 main phases in nested scrolling system:
1. Pre-scroll. This callback is triggered when the descendant is about to perform a scroll operation and gives parent an opportunity to consume part of child's delta beforehand. This pass should happen every time scrollable components receives delta and dispatches it via `NestedScrollDispatcher`. Dispatching child should take into account how much all ancestors above the hierarchy consumed and adjust the consumption accordingly.
2. Post-scroll. This callback is triggered when the descendant consumed the delta already (after taking into account what parents pre-consumed in 1.) and wants to notify the ancestors with the amount of delta unconsumed. This pass should happen every time scrollable components receives delta and dispatches it via `NestedScrollDispatcher`. Any parent that receives `NestedScrollConnection.onPostScroll` should consume no more than `left` and return the amount consumed.
3. Pre-fling. Pass that happens when the scrolling descendant stopped dragging and about to fling with the some velocity. This callback allows ancestors to consume part of the velocity. This pass should happen before the fling itself happens. Similar to pre-scroll, parent can consume part of the velocity and nodes below (including the dispatching child) should adjust their logic to accommodate only the velocity left.
4. Post-fling. Pass that happens after the scrolling descendant stopped flinging and wants to notify ancestors about that fact, providing velocity left to consume as a part of this. This pass should happen after the fling itself happens on the scrolling child. Ancestors of the dispatching node will have opportunity to fling themselves with the `velocityLeft` provided. Parent must call `notifySelfFinish` callback in order to continue the propagation of the velocity that is left to ancestors above.
`androidx.compose.foundation.lazy.LazyColumn`, `androidx.compose.foundation.verticalScroll` and
`androidx.compose.foundation.gestures.scrollable` have build in support for nested scrolling,
however, it's desirable to be able to react and influence their scroll via nested scroll system.
**Note:** The nested scroll system is orientation independent. This mean it is based off the
screen direction (x and y coordinates) rather than being locked to a specific orientation.
#### Parameters
| | |
| --- | --- |
| connection | connection to the nested scroll system to participate in the event chaining, receiving events when scrollable descendant is being scrolled. |
| dispatcher | object to be attached to the nested scroll system on which `dispatch*` methods can be called to notify ancestors within nested scroll system about scrolling happening |