BringIntoViewSpec


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

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

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 {
        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 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>

This property is deprecated. Animation spec customization is no longer supported.

Cmn

Public functions

calculateScrollDistance

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

open val scrollAnimationSpecAnimationSpec<Float>

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