A snapping fling behavior for Jetpack Compose

We have horizontally scrollable container/content. It contains about 1 to 3 (at most) containers. The design requires to have the boxes the same height, so we use intrinsic height sizing (and of course, the width is also the same). Using intrinsic is forbidden in LazyRow, so we are currently using normal scrollable Row.

It could be probably done via custom SnapperLayoutInfo, yet it seems like enormous and non trivial work/amount of code.

Do you have any idea how to make it easier?

Solution I'd like I am not much sure, maybe something like this?

val state = rememberScrollState()
val flingBehavior = rememberSnapperFlingBehavior(state, itemWidth = 200.dp)
Row(
    Modifier
        .horizontalScroll(
            state = state,
            flingBehavior = flingBehavior,
        )
)

Alternatives I've considered

• having custom snapping code (what we have now)
• implementing SnapperLayoutInfo

Describe the bug

The app crashes when trying to call the rememberSnapperFlingBehavior() function

To Reproduce

Using rememberSnapperFlingBehavior() instantly crashes my app since i have updated to the 0.3.0 version

Expected behavior

No crash occurs

Environment:

• Android OS version: android 13
• Device: Pixel 5
• Library version: 0.3.0

Exception Message:

java.lang.NoSuchMethodError: No static method rememberSnapperFlingBehavior-TN_CM5M(Landroidx/compose/foundation/lazy/LazyListState;Lkotlin/jvm/functions/Function2;FLandroidx/compose/animation/core/DecayAnimationSpec;Landroidx/compose/animation/core/AnimationSpec;Landroidx/compose/runtime/Composer;II)Ldev/chrisbanes/snapper/SnapperFlingBehavior; in class Ldev/chrisbanes/snapper/LazyListKt; or its super classes (declaration of 'dev.chrisbanes.snapper.LazyListKt' appears in ,,,

Describe the bug

Hi, Thanks for library. It is great!

I've got issues when trying to get current item. LayoutInfo's return the same currentItem.index for two latest items. For example, when I got 4 items, after scroll one by one (horizontally) layoutInfo.currentItem?.index should returns 0, 1, 2, 3 index values, however it returns 0, 1, 2, 2 values.

Here is simplified implementation to reproduce issue:

@OptIn(ExperimentalSnapperApi::class)
@Composable
fun TestCode(titles: List<String>) {
    val contentPadding = PaddingValues(start = 16.dp,
                                       end = 16.dp)
    val lazyListState = rememberLazyListState()
    val layoutInfo = rememberLazyListSnapperLayoutInfo(lazyListState,
                                                       snapOffsetForItem = SnapOffsets.Center,
                                                       endContentPadding = contentPadding.calculateEndPadding(LayoutDirection.Ltr))

    LaunchedEffect(lazyListState.isScrollInProgress) {
        if (!lazyListState.isScrollInProgress) {
            val index = layoutInfo.currentItem?.index
            // index will never be equals to last item index.
            // two last items will returns the same index
        }
    }

    LazyRow(
        state = lazyListState,
        contentPadding = contentPadding,
        flingBehavior = rememberSnapperFlingBehavior(layoutInfo),
        horizontalArrangement = Arrangement.spacedBy(24.dp),
        modifier = Modifier.fillMaxWidth()
    ) {
        items(titles) { title ->
            TextField(text = title)
        }
    }
}

Environment:

• Android OS 11, 12
• OnePlus7T PRO, Android Emulator
• Library version: both 0.1.0 and 0.2.0

Describe the bug

LazyList with snapper doesn't scroll to the item defined by initialFirstVisibleItemIndex.

To Reproduce

Steps to reproduce the behavior:

val lazyListState = rememberLazyListState(initialFirstVisibleItemIndex = 3)

val flingBehavior = rememberSnapperFlingBehavior(
    lazyListState = lazyListState,
    endContentPadding = contentPadding.calculateEndPadding(LayoutDirection.Ltr),
)

LazyRow(
    state = lazyListState,
    flingBehavior = flingBehavior
) {
    items(5) {
        // show item here
    }
}

Expected behavior

On the initial display (or first launch), the lazylist should auto-scroll to 3rd item. The lazylist shouldn't scroll after display but rather scroll to the correct initial item index before displaying.

Actual behavior

On initial display, the lazylist shows 1st item as the 1st visible item.

To work this issue around, I am using a side affect to scroll to the initial page when the screen is shown

val lazyListState = rememberLazyListState(initialFirstVisibleItemIndex = 3)

// workaround
LaunchedEffect(Unit) {
    lazyListState.animateScrollToItem(initialPage)
}

val flingBehavior = rememberSnapperFlingBehavior(
    lazyListState = lazyListState,
    endContentPadding = contentPadding.calculateEndPadding(LayoutDirection.Ltr),
)

LazyRow(
    state = lazyListState,
    flingBehavior = flingBehavior
) {
    items(5) {
        // show item here
    }
}

Screenshots?

If applicable, add screenshots to help explain your problem.

Environment:

• Android OS version: 13
• Device: Google Pixel 4a
• Library version: 0.2.2

Additional context

Add any other context about the problem here.

Describe the bug

Trying to snap when item indexes are large numbers, snapper snaps back to the current item

To Reproduce

Minimal reproducible sample:

@OptIn(ExperimentalSnapperApi::class)
@Composable
fun SnapperBug() {
    val modifier = Modifier
        .fillMaxWidth()
        .aspectRatio(1f)
    val lazyListState = rememberLazyListState(
        initialFirstVisibleItemIndex = Int.MAX_VALUE / 2
    )
    LazyRow(
        modifier = modifier,
        state = lazyListState,
        flingBehavior = rememberSnapperFlingBehavior(lazyListState)
    ) {
        items(
            count = Int.MAX_VALUE,
            key = { it }
        ) { index ->
            Box(modifier) {
                Text(
                    index.toString(),
                    modifier = Modifier.align(Alignment.Center)
                )
            }
        }
    }
}

Steps to reproduce:

1. Load the above Composable
2. Scroll once, note the first scroll is successful
3. Try to scroll again, note snapper now snaps back to the initial item immediately.

Expected behavior

Snapper continues to snap across the entire range of items

Screenshots?

I can attach a video if necessary

Environment:

• Android OS version: 12L (API32)
• Device: Resizable Emulator
• Library version: 0.1.2
• Compose version: 1.2.0-alpha02 (Also reproducible with Compose 1.1.0-rc01)

Additional context

If you significantly lower the initial page in the above sample, snapper starts to work normally

Is your feature request related to a problem? Please describe. I want to use this library with pager from accompanist in my Compose for Desktop app.

Describe the solution you'd like Add support for compose-jb to be able to use this as a multiplatform library, the code looks to not depend on android only code so it should be possible.

Describe alternatives you've considered If not, I can fork this and make a new version that supports Compose for Desktop.

Additional context I have migrated all my android app from xml + fragments to compose only to make my app work for desktop as well and it works well, but I need a Pager and I can't use accompanist because it supports Android only.

Hi @chrisbanes . I need a feature to snap n items, not only one. I'd appreciate if you'll look on my changes to support this case or at least to say if snapper is going to support this case.

Describe the bug

Using unsafe nullable type in the ScrollScope.performFling function, which causes crash

  override suspend fun ScrollScope.performFling(
        initialVelocity: Float
    ): Float {
        // If we're at the start/end of the scroll range, we don't snap and assume the user
        // wanted to scroll here.
        if (!layoutInfo.canScrollTowardsStart() || !layoutInfo.canScrollTowardsEnd()) {
            return initialVelocity
        }

        SnapperLog.d { "performFling. initialVelocity: $initialVelocity" }

        val maxFlingDistance = maximumFlingDistance(layoutInfo)
        require(maxFlingDistance > 0) {
            "Distance returned by maximumFlingDistance should be greater than 0"
        }

        val targetIndex = layoutInfo.determineTargetIndex(
            velocity = initialVelocity,
            decayAnimationSpec = decayAnimationSpec,
            maximumFlingDistance = maxFlingDistance,
        ).let { target ->
            // Let the snapIndex block transform the value
            val start = layoutInfo.**currentItem!!**.index.let { index ->
                // If the user is flinging towards the index 0, we assume that the start item is
                // actually the next item (towards infinity).
                if (initialVelocity < 0) index + 1 else index
            }
            snapIndex(layoutInfo, start, target)
        }.also {
            require(it in 0 until layoutInfo.totalItemsCount)
        }

        return flingToIndex(index = targetIndex, initialVelocity = initialVelocity)
    }

Additional context

This unsafe nullable type is used in two other places as well ->

• SemanticsNodeInteraction.swipeAcrossCenterWithVelocity func
• ScrollScope.flingToIndex func

The documentation states:

decayAnimationSpec is the main spec used for flinging, and is used when the fling has enough velocity to scroll past the current item.

However, how do you actually configure what is 'enough' velocity? I've noticed that the default velocity doesn't fit my needs very well. Arpit Shukla described this very well 10 months ago:

Sometimes I gently swipe to the left or right and expect that I will move to the next page, but that doesn't happen, the page moves a little and then comes back. Then I realize that I need to put more effort and swipe a little more :sweat_smile:. I was thinking if it is possible to change that threshold velocity which is required to switch pages. I checked few other apps which provide a pager with a tab layout and there I can change pages with the slightest swipe.

Attaching a video to give more context to the behavior I was referring to.

https://user-images.githubusercontent.com/25990014/192085480-0d8cf1a2-4adb-4ad0-b04b-64f11eb8ee98.mp4

Perhaps it is configurable, but I cannot find how.

Is your feature request related to a problem? Please describe. Sometimes due to a design request (like having all items in a carousel be the same height (using intrinsics) I cannot use lazy*, but I would love to have snapping behavior.

This block which returns the index which the apps wishes to snap to. The block is provided with the SnapperLayoutInfo and the index which Snapper has determined is the correct target index. Callers can override this value as they see fit.

A common use case could be rounding up/down to achieve groupings of items, which was the intention of #12.

A very simple version could look this this:

val GroupSize = 3

flingBehavior = rememberSnapperFlingBehavior(
    lazyListState = lazyListState,
    snapIndex = { layout, targetIndex ->
        val mod = targetIndex % GroupSize
        if (mod > (GroupSize / 2)) {
            // Round up towards infinity
            GroupSize + targetIndex - mod
        } else {
            // Round down towards zero
            targetIndex - mod
        }
    }
),

You could also look at the layout.currentItem to determine the fling direction to influence which direction to round.

How do I scroll to an item programmatically?

Also, how do I scroll "past" the beginning or end so that the first or last items of the list can also be in the center and be "selected"

I am using this for a selectable list of items. Items can be selected either by:

• tapping on them (triggering a scroll to put the selected item in the center)
• scrolling until the item is in the center
• Programmatically by updating the selected index from another function

Would this be possible?

It compiles but doesn't work on desktop due to https://github.com/JetBrains/compose-jb/issues/1423. Will need to wait for that to be fixed before continuing.

#5