BringIntoViewSpec

The configuration of how a scrollable reacts to bring into view requests.

Note: API shape and naming are still being refined, therefore API is marked as experimental.

Check the following sample for a use case usage of this API:

import androidx.compose.animation.core.AnimationSpec
import androidx.compose.animation.core.LinearEasing
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.focusable
import androidx.compose.foundation.gestures.BringIntoViewSpec
import androidx.compose.foundation.gestures.LocalBringIntoViewSpec
import androidx.compose.foundation.gestures.scrollable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.items
import androidx.compose.material.Text
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// a bring into view spec that pivots around the center of the scrollable container
val customBringIntoViewSpec = object : BringIntoViewSpec {
    val customAnimationSpec = tween<Float>(easing = LinearEasing)
    override val scrollAnimationSpec: AnimationSpec<Float>
        get() = customAnimationSpec

    override fun calculateScrollDistance(
        offset: Float,
        size: Float,
        containerSize: Float
    ): Float {
        val trailingEdgeOfItemRequestingFocus = offset + size

        val sizeOfItemRequestingFocus =
            abs(trailingEdgeOfItemRequestingFocus - offset)
        val childSmallerThanParent = sizeOfItemRequestingFocus <= containerSize
        val initialTargetForLeadingEdge =
            containerSize / 2f - (sizeOfItemRequestingFocus / 2f)
        val spaceAvailableToShowItem = containerSize - initialTargetForLeadingEdge

        val targetForLeadingEdge =
            if (childSmallerThanParent &&
                spaceAvailableToShowItem < sizeOfItemRequestingFocus
            ) {
                containerSize - sizeOfItemRequestingFocus
            } else {
                initialTargetForLeadingEdge
            }

        return offset - targetForLeadingEdge
    }
}

// LocalBringIntoViewSpec will apply to all scrollables in the hierarchy.
CompositionLocalProvider(LocalBringIntoViewSpec provides customBringIntoViewSpec) {
    LazyRow(
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
    ) {
        items(100) {
            var color by remember { mutableStateOf(Color.White) }
            Box(
                modifier = Modifier
                    .size(100.dp)
                    .padding(4.dp)
                    .background(Color.Gray)
                    .onFocusChanged {
                        color = if (it.isFocused) Color.Red else Color.White
                    }
                    .border(5.dp, color)
                    .focusable(),
                contentAlignment = Alignment.Center
            ) {
                Text(text = it.toString())
            }
        }
    }
}

Summary

Public companion properties
AnimationSpec<Float>

The default animation spec used by Modifier.scrollable to run Bring Into View requests.
Cmn

Public functions
open Float
calculateScrollDistance(offset: Float, size: Float, containerSize: Float)

Calculate the offset needed to bring one of the scrollable container's child into view.
Cmn

Public properties
open AnimationSpec<Float>

An Animation Spec to be used as the animation to run to fulfill the BringIntoView requests.
Cmn

Public companion properties

DefaultScrollAnimationSpec

Cmn
Added in 1.6.0
val DefaultScrollAnimationSpec: AnimationSpec<Float>

The default animation spec used by Modifier.scrollable to run Bring Into View requests.

Public functions

calculateScrollDistance

Cmn
Added in 1.6.0
open fun calculateScrollDistance(offset: Float, size: Float, containerSize: Float): Float

Calculate the offset needed to bring one of the scrollable container's child into view. This will be called for every frame of the scrolling animation. This means that, as the animation progresses, the offset will naturally change to fulfill the scroll request.

All distances below are represented in pixels.

Parameters
offset: Float

from the side closest to the start of the container.
size: Float

is the child size.
containerSize: Float

Is the main axis size of the scrollable container.
Returns
Float

The necessary amount to scroll to satisfy the bring into view request. Returning zero from here means that the request was satisfied and the scrolling animation should stop.

Public properties

scrollAnimationSpec

Cmn
Added in 1.6.0
open val scrollAnimationSpec: AnimationSpec<Float>

An Animation Spec to be used as the animation to run to fulfill the BringIntoView requests.