scrollAway

Modifier in Wear Material 3 Compose

Scroll an item vertically in/out of view based on scroll state provided by a scrolling list. Typically used to scroll a [TimeText] item out of view as the user starts to scroll a vertically scrollable list of items upwards and bring additional items into view.

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha27")
}

Overloads

fun Modifier.scrollAway(
    scrollInfoProvider: ScrollInfoProvider,
    screenStage: () -> ScreenStage
): Modifier

Parameters

name	description
scrollInfoProvider	Used as the basis for the scroll-away implementation, based on the state of the scrollable container. See [ScrollInfoProvider] methods for creating a ScrollInfoProvider from common lists such as [ScalingLazyListState].
screenStage	Function that returns the screen stage of the active screen. Scrolled away items are shown when the screen is new, then scrolled away or hidden when scrolling, and finally shown again when idle.

Code Example

ScrollAwaySample

@Composable
fun ScrollAwaySample() {
    val state = rememberScalingLazyListState()

    Box(modifier = Modifier.fillMaxSize()) {
        ScalingLazyColumn(
            state = state,
            modifier = Modifier.fillMaxSize(),
            autoCentering = AutoCenteringParams(itemIndex = 10)
        ) {
            item {
                ListHeader {
                    Text(
                        modifier = Modifier.fillMaxWidth(),
                        text = "ScalingLazyColumn",
                        textAlign = TextAlign.Center
                    )
                }
            }
            items(50) {
                FilledTonalButton(
                    modifier = Modifier.fillMaxWidth().padding(horizontal = 36.dp),
                    onClick = {},
                    label = { Text("Item ${it + 1}") },
                )
            }
        }
        TimeText(
            // In practice, it is recommended to use the [AppScaffold] and [ScreenScaffold],
            // so that the Material3 scroll away behavior is provided by default, rather than using
            // [Modifier.scrollAway] directly.
            modifier =
                Modifier.scrollAway(
                    scrollInfoProvider = ScrollInfoProvider(state),
                    screenStage = {
                        if (state.isScrollInProgress) ScreenStage.Scrolling else ScreenStage.Idle
                    }
                ),
            content = {
                text("ScrollAway")
                separator()
                time()
            }
        )
    }
}