Interface
Common
```kotlin
interface OverscrollEffect
```
An OverscrollEffect represents a visual effect that displays when the edges of a scrolling
container have been reached with a scroll or fling. To create an instance of the default /
currently provided `OverscrollFactory`, use `rememberOverscrollEffect`.
To implement, make sure to override `node` - this has a default implementation for compatibility
reasons, but is required for an OverscrollEffect to render.
OverscrollEffect conceptually 'decorates' scroll / fling events: consuming some of the delta or
velocity before and/or after the event is consumed by the scrolling container. `applyToScroll`
applies overscroll to a scroll event, and `applyToFling` applies overscroll to a fling.
Higher level components such as `androidx.compose.foundation.lazy.LazyColumn` will automatically
configure an OverscrollEffect for you. To use a custom OverscrollEffect you first need to provide
it with scroll and/or fling events - usually by providing it to a
`androidx.compose.foundation.gestures.scrollable`. Then you can draw the effect on top of the
scrolling content using `Modifier.overscroll`.
## Properties
Common
```kotlin
val isInProgress: Boolean
```
Whether this OverscrollEffect is currently displaying overscroll.
#### Returns
| | |
| --- | --- |
| | true if this OverscrollEffect is currently displaying overscroll |
Common
> **Deprecated** This has been replaced with `node`. If you are calling this property to render overscroll, use Modifier.overscroll() instead. If you are implementing OverscrollEffect, override `node` instead to render your overscroll.
```kotlin
val effectModifier: Modifier
```
A `Modifier` that will draw this OverscrollEffect
This API is deprecated- implementers should instead override `node`. Callers should use
`Modifier.overscroll`.
Common
```kotlin
val node: DelegatableNode
```
The `DelegatableNode` that will render this OverscrollEffect and provide any required size or
other information to this effect.
In most cases you should use `Modifier.overscroll` to render this OverscrollEffect, which
will internally attach this node to the hierarchy. The node should be attached before
`applyToScroll` or `applyToFling` is called to ensure correctness.
This property should return a single instance, and can only be attached once, as with other
`DelegatableNode`s.
## Functions
```kotlin
fun applyToScroll(
delta: Offset,
source: NestedScrollSource,
performScroll: (Offset) -> Offset,
): Offset
```
Applies overscroll to `performScroll`. `performScroll` should represent a drag / scroll, and
returns the amount of delta consumed, so in simple cases the amount of overscroll to show
should be equal to `delta - performScroll(delta)`. The OverscrollEffect can optionally
consume some delta before calling `performScroll`, such as to release any existing tension.
The implementation *must* call `performScroll` exactly once. This function should return the
sum of all the delta that was consumed during this operation - both by the overscroll and
`performScroll`.
For example, assume we want to apply overscroll to a custom component that isn't using
`androidx.compose.foundation.gestures.scrollable`. Here is a simple example of a component
using `androidx.compose.foundation.gestures.draggable` instead:
To apply overscroll, we need to decorate the existing logic with applyToScroll, and return
the amount of delta we have consumed when updating the drag position. Note that we also need
to call applyToFling - this is used as an end signal for overscroll so that effects can
correctly reset after any animations, when the gesture has stopped.
#### Parameters
| | |
| --- | --- |
| delta | total scroll delta available |
| source | the source of the delta |
| performScroll | the scroll action that the overscroll is applied to. The `Offset` parameter represents how much delta is available, and the return value is how much delta was consumed. Any delta that was not consumed should be used to show the overscroll effect. |
#### Returns
| | |
| --- | --- |
| | the delta consumed from `delta` by the operation of this function - including that consumed by `performScroll`. |
```kotlin
suspend fun applyToFling(velocity: Velocity, performFling: suspend (Velocity) -> Velocity)
```
Applies overscroll to `performFling`. `performFling` should represent a fling (the release of
a drag or scroll), and returns the amount of `Velocity` consumed, so in simple cases the
amount of overscroll to show should be equal to `velocity - performFling(velocity)`. The
OverscrollEffect can optionally consume some `Velocity` before calling `performFling`, such
as to release any existing tension. The implementation *must* call `performFling` exactly
once.
For example, assume we want to apply overscroll to a custom component that isn't using
`androidx.compose.foundation.gestures.scrollable`. Here is a simple example of a component
using `androidx.compose.foundation.gestures.draggable` instead:
To apply overscroll, we decorate the existing logic with applyToScroll, and return the amount
of delta we have consumed when updating the drag position. We then call applyToFling using
the velocity provided by onDragStopped.
#### Parameters
| | |
| --- | --- |
| velocity | total `Velocity` available |
| performFling | the `Velocity` consuming lambda that the overscroll is applied to. The `Velocity` parameter represents how much `Velocity` is available, and the return value is how much `Velocity` was consumed. Any `Velocity` that was not consumed should be used to show the overscroll effect. |