androidx.wear.compose.foundation.lazy

@Composable
fun ScalingLazyColumn(
    modifier: Modifier = Modifier,
    state: ScalingLazyListState = rememberScalingLazyListState(),
    contentPadding: PaddingValues = PaddingValues(horizontal = 10.dp),
    reverseLayout: Boolean = false,
    verticalArrangement: Arrangement.Vertical = Arrangement.spacedBy(
            space = 4.dp,
            alignment = if (!reverseLayout) Alignment.Top else Alignment.Bottom
        ),
    horizontalAlignment: Alignment.Horizontal = Alignment.CenterHorizontally,
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
    userScrollEnabled: Boolean = true,
    scalingParams: ScalingParams = ScalingLazyColumnDefaults.scalingParams(),
    anchorType: ScalingLazyListAnchorType = ScalingLazyListAnchorType.ItemCenter,
    autoCentering: AutoCenteringParams? = AutoCenteringParams(),
    rotaryBehavior: RotaryBehavior? = RotaryDefaults.scrollBehavior(scrollableState = state),
    content: ScalingLazyListScope.() -> Unit
): Unit

A scrolling scaling/fisheye list component that forms a key part of the Wear Material Design language. Provides scaling and transparency effects to the content items.

ScalingLazyColumn is designed to be able to handle potentially large numbers of content items. Content items are only materialized and composed when needed.

If scaling/fisheye functionality is not required then a LazyColumn should be considered instead to avoid any overhead of measuring and calculating scaling and transparency effects for the content items.

This overload supports rotary input. Rotary input allows users to scroll the content of the ScalingLazyColumn - by using a crown or a rotating bezel on their Wear OS device. It can be modified with rotaryBehavior param. If scroll with fling is required use RotaryDefaults.scrollBehavior. If snapping is required use RotaryDefaults.snapBehavior. Note that rotary scroll and touch scroll should be aligned. If rotaryBehavior is set for snap (using RotaryDefaults.snapBehavior), flingBehavior should be set for snap as well (using ScalingLazyColumnDefaults.snapFlingBehavior). This composable uses rememberActiveFocusRequester as FocusRequester for rotary support. It requires that this ScalingLazyColumn should be wrapped by HierarchicalFocusCoordinator. By default HierarchicalFocusCoordinator is already implemented in BasicSwipeToDismissBox, which is a part of material Scaffold - meaning that rotary will be able to request a focus without any additional changes. Another FocusRequester can be added through Modifier chain by adding .focusRequester(focusRequester). Do not call focusable() after it as this will reset the focusRequester chain and rotary support will not be available.

Example of a ScalingLazyColumn with default parameters:

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.ui.Modifier
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.material.Chip
import androidx.wear.compose.material.ChipDefaults
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text

ScalingLazyColumn(
    modifier = Modifier.fillMaxWidth()
) {
    item {
        ListHeader {
            Text(text = "List Header")
        }
    }
    items(20) {
        Chip(
            onClick = { },
            label = { Text("List item $it") },
            colors = ChipDefaults.secondaryChipColors()
        )
    }
}

Example of a ScalingLazyColumn using ScalingLazyListAnchorType.ItemStart anchoring, in this configuration the edge of list items is aligned to the center of the screen. Also this example shows scrolling to a clicked list item with ScalingLazyListState.animateScrollToItem:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.wear.compose.foundation.lazy.AutoCenteringParams
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.foundation.lazy.ScalingLazyListAnchorType
import androidx.wear.compose.foundation.lazy.rememberScalingLazyListState
import androidx.wear.compose.material.Chip
import androidx.wear.compose.material.ChipDefaults
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text

val coroutineScope = rememberCoroutineScope()
val itemSpacing = 6.dp
// Line up the gap between the items on the center-line
val scrollOffset = with(LocalDensity.current) {
    -(itemSpacing / 2).roundToPx()
}
val state = rememberScalingLazyListState(
    initialCenterItemIndex = 1,
    initialCenterItemScrollOffset = scrollOffset
)

ScalingLazyColumn(
    modifier = Modifier.fillMaxWidth(),
    anchorType = ScalingLazyListAnchorType.ItemStart,
    verticalArrangement = Arrangement.spacedBy(itemSpacing),
    state = state,
    autoCentering = AutoCenteringParams(itemOffset = scrollOffset)
) {
    item {
        ListHeader {
            Text(text = "List Header")
        }
    }
    items(20) {
        Chip(
            onClick = {
                coroutineScope.launch {
                    // Add +1 to allow for the ListHeader
                    state.animateScrollToItem(it + 1, scrollOffset)
                }
            },
            label = { Text("List item $it") },
            colors = ChipDefaults.secondaryChipColors()
        )
    }
}

Example of a ScalingLazyColumn with snap of items to the viewport center:

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.ui.Modifier
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.foundation.lazy.ScalingLazyColumnDefaults
import androidx.wear.compose.foundation.lazy.rememberScalingLazyListState
import androidx.wear.compose.foundation.rotary.RotaryDefaults
import androidx.wear.compose.material.Chip
import androidx.wear.compose.material.ChipDefaults
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text

val state = rememberScalingLazyListState()
ScalingLazyColumn(
    rotaryBehavior = RotaryDefaults.snapBehavior(state = state),
    flingBehavior = ScalingLazyColumnDefaults.snapFlingBehavior(state = state),
    modifier = Modifier.fillMaxWidth(),
    state = state,
) {
    item {
        ListHeader {
            Text(text = "List Header")
        }
    }
    items(20) {
        Chip(
            onClick = { },
            label = { Text("List item $it") },
            colors = ChipDefaults.secondaryChipColors()
        )
    }
}

Example of a ScalingLazyColumn where autoCentering has been disabled and explicit contentPadding provided to ensure there is space above the first and below the last list item to allow them to be scrolled into view on circular screens:

import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.material.Chip
import androidx.wear.compose.material.ChipDefaults
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text

ScalingLazyColumn(
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(top = 20.dp, bottom = 20.dp),
    autoCentering = null
) {
    item {
        ListHeader {
            Text(text = "List Header")
        }
    }
    items(20) {
        Chip(
            onClick = { },
            label = { Text("List item $it") },
            colors = ChipDefaults.secondaryChipColors()
        )
    }
}

For more information, see the Lists guide.

@Composable
fun rememberScalingLazyListState(
    initialCenterItemIndex: Int = 1,
    initialCenterItemScrollOffset: Int = 0
): ScalingLazyListState

Creates a ScalingLazyListState that is remembered across compositions.

inline fun <T : Any?> ScalingLazyListScope.items(
    items: Array<T>,
    noinline key: ((item) -> Any)? = null,
    crossinline itemContent: @Composable ScalingLazyListItemScope.(item) -> Unit
): Unit

Adds an array of items.

inline fun <T : Any?> ScalingLazyListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)? = null,
    crossinline itemContent: @Composable ScalingLazyListItemScope.(item) -> Unit
): Unit

Adds a list of items.

inline fun <T : Any?> ScalingLazyListScope.itemsIndexed(
    items: Array<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline itemContent: @Composable ScalingLazyListItemScope.(index: Int, item) -> Unit
): Unit

Adds an array of items where the content of an item is aware of its index.

inline fun <T : Any?> ScalingLazyListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline itemContent: @Composable ScalingLazyListItemScope.(index: Int, item) -> Unit
): Unit

Adds a list of items where the content of an item is aware of its index.