{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SnapFlingBehavior

@ExperimentalFoundationApi
public final class SnapFlingBehavior implements FlingBehavior


A FlingBehavior that performs snapping of items to a given position. The algorithm will differentiate between short/scroll snapping and long/fling snapping.

Use shortSnapVelocityThreshold to provide a threshold velocity that will appropriately select the desired behavior.

A short snap usually happens after a fling with low velocity.

When long snapping, you can use SnapLayoutInfoProvider.calculateApproachOffset to indicate that snapping should happen after this offset. If the velocity generated by the fling is high enough to get there, we'll use highVelocityAnimationSpec to get to that offset and then we'll snap to the next bound calculated by SnapLayoutInfoProvider.calculateSnappingOffset using snapAnimationSpec.

If the velocity is not high enough, we'll use lowVelocityAnimationSpec to approach and then use snapAnimationSpec to snap into place.

Please refer to the sample to learn how to use this API.

import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.snapping.rememberSnapFlingBehavior
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.material.Text
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.unit.dp
import androidx.compose.ui.unit.sp

val state = rememberLazyListState()

LazyRow(
    modifier = Modifier.fillMaxSize(),
    verticalAlignment = Alignment.CenterVertically,
    state = state,
    flingBehavior = rememberSnapFlingBehavior(lazyListState = state)
) {
    items(200) {
        Box(
            modifier = Modifier
                .height(400.dp)
                .width(200.dp)
                .padding(8.dp)
                .background(Color.Gray),
            contentAlignment = Alignment.Center
        ) {
            Text(it.toString(), fontSize = 32.sp)
        }
    }
}
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.snapping.SnapLayoutInfoProvider
import androidx.compose.foundation.gestures.snapping.rememberSnapFlingBehavior
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.material.Text
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.unit.dp
import androidx.compose.ui.unit.sp

val state = rememberLazyListState()

// If you'd like to customize either the snap behavior or the layout provider
val snappingLayout = remember(state) { SnapLayoutInfoProvider(state) }
val flingBehavior = rememberSnapFlingBehavior(snappingLayout)

LazyRow(
    modifier = Modifier.fillMaxSize(),
    verticalAlignment = Alignment.CenterVertically,
    state = state,
    flingBehavior = flingBehavior
) {
    items(200) {
        Box(
            modifier = Modifier
                .height(400.dp)
                .width(200.dp)
                .padding(8.dp)
                .background(Color.Gray),
            contentAlignment = Alignment.Center
        ) {
            Text(it.toString(), fontSize = 32.sp)
        }
    }
}

Summary

Public constructors

SnapFlingBehavior(
    @NonNull SnapLayoutInfoProvider snapLayoutInfoProvider,
    @NonNull AnimationSpec<@NonNull Float> lowVelocityAnimationSpec,
    @NonNull DecayAnimationSpec<@NonNull Float> highVelocityAnimationSpec,
    @NonNull AnimationSpec<@NonNull Float> snapAnimationSpec,
    @NonNull Density density,
    @NonNull Dp shortSnapVelocityThreshold
)

Public methods

boolean
equals(Object other)
int
float
performFling(@NonNull ScrollScope receiver, float initialVelocity)

Perform settling via fling animation with given velocity and suspend until fling has finished.

final float
performFling(
    @NonNull ScrollScope receiver,
    float initialVelocity,
    @NonNull Function1<@NonNull FloatUnit> onSettlingDistanceUpdated
)

Perform a snapping fling animation with given velocity and suspend until fling has finished.

Public constructors

SnapFlingBehavior

public SnapFlingBehavior(
    @NonNull SnapLayoutInfoProvider snapLayoutInfoProvider,
    @NonNull AnimationSpec<@NonNull Float> lowVelocityAnimationSpec,
    @NonNull DecayAnimationSpec<@NonNull Float> highVelocityAnimationSpec,
    @NonNull AnimationSpec<@NonNull Float> snapAnimationSpec,
    @NonNull Density density,
    @NonNull Dp shortSnapVelocityThreshold
)
Parameters
@NonNull SnapLayoutInfoProvider snapLayoutInfoProvider

The information about the layout being snapped.

@NonNull AnimationSpec<@NonNull Float> lowVelocityAnimationSpec

The animation spec used to approach the target offset. When the fling velocity is not large enough. Large enough means large enough to naturally decay.

@NonNull DecayAnimationSpec<@NonNull Float> highVelocityAnimationSpec

The animation spec used to approach the target offset. When the fling velocity is large enough. Large enough means large enough to naturally decay.

@NonNull AnimationSpec<@NonNull Float> snapAnimationSpec

The animation spec used to finally snap to the correct bound.

@NonNull Density density

The screen Density

@NonNull Dp shortSnapVelocityThreshold

Use the given velocity to determine if it's a short or long snap.

Public methods

equals

public boolean equals(Object other)

hashCode

public int hashCode()

performFling

public float performFling(@NonNull ScrollScope receiver, float initialVelocity)

Perform settling via fling animation with given velocity and suspend until fling has finished.

This functions is called with ScrollScope to drive the state change of the androidx.compose.foundation.gestures.ScrollableState via ScrollScope.scrollBy.

This function must return correct velocity left after it is finished flinging in order to guarantee proper nested scroll support.

Parameters
float initialVelocity

velocity available for fling in the orientation specified in androidx.compose.foundation.gestures.scrollable that invoked this method.

Returns
float

remaining velocity after fling operation has ended

performFling

public final float performFling(
    @NonNull ScrollScope receiver,
    float initialVelocity,
    @NonNull Function1<@NonNull FloatUnit> onSettlingDistanceUpdated
)

Perform a snapping fling animation with given velocity and suspend until fling has finished. This will behave the same way as performFling except it will report on each remainingOffsetUpdate using the onSettlingDistanceUpdated lambda.

Parameters
float initialVelocity

velocity available for fling in the orientation specified in androidx.compose.foundation.gestures.scrollable that invoked this method.

@NonNull Function1<@NonNull FloatUnit> onSettlingDistanceUpdated

a lambda that will be called anytime the distance to the settling offset is updated. The settling offset is the final offset where this fling will stop and may change depending on the snapping animation progression.

Returns
float

remaining velocity after fling operation has ended