New Compose Multiplatform components arrived on Composables UICheck it out →

← Component in Compose Foundation

LazyVerticalStaggeredGrid

Common

Vertical staggered grid layout that composes and lays out only items currently visible on screen.

Last updated:

Installation

dependencies {
   implementation("androidx.compose.foundation:foundation:1.7.0-beta04")
}

Overloads

@Composable
fun LazyVerticalStaggeredGrid(
    columns: StaggeredGridCells,
    modifier: Modifier = Modifier,
    state: LazyStaggeredGridState = rememberLazyStaggeredGridState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    reverseLayout: Boolean = false,
    verticalItemSpacing: Dp = 0.dp,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.spacedBy(0.dp),
    flingBehavior: FlingBehavior = ScrollableDefaults.flingBehavior(),
    userScrollEnabled: Boolean = true,
    content: LazyStaggeredGridScope.() -> Unit
)

Parameters

namedescription
columnsdescription of the size and number of staggered grid columns.
modifiermodifier to apply to the layout.
statestate object that can be used to control and observe staggered grid state.
contentPaddingpadding around the content.
reverseLayoutreverse the direction of scrolling and layout. When true, items are laid out in the reverse order and [LazyStaggeredGridState.firstVisibleItemIndex] == 0 means that grid is scrolled to the bottom.
verticalItemSpacingvertical spacing between items.
horizontalArrangementarrangement specifying horizontal spacing between items. The item arrangement specifics are ignored for now.
flingBehaviorlogic responsible for handling fling.
userScrollEnabledwhether scroll with gestures or accessibility actions are allowed. It is still possible to scroll programmatically through state when [userScrollEnabled] is set to false
contenta lambda describing the staggered grid content. Inside this block you can use [LazyStaggeredGridScope.items] to present list of items or [LazyStaggeredGridScope.item] for a single one.

Code Examples

LazyVerticalStaggeredGridSample

@Composable
@Preview
@Sampled
fun LazyVerticalStaggeredGridSample() {
    val itemsList = (0..5).toList()
    val itemsIndexedList = listOf("A", "B", "C")

    val itemModifier = Modifier.border(1.dp, Color.Blue).wrapContentSize()

    LazyVerticalStaggeredGrid(
        columns = StaggeredGridCells.Fixed(3)
    ) {
        items(itemsList) {
            Text("Item is $it", itemModifier.height(80.dp))
        }
        item {
            Text("Single item", itemModifier.height(100.dp))
        }
        itemsIndexed(itemsIndexedList) { index, item ->
            Text("Item at index $index is $item", itemModifier.height(60.dp))
        }
    }
}

LazyVerticalStaggeredGridSpanSample

@Composable
@Preview
@Sampled
fun LazyVerticalStaggeredGridSpanSample() {
    val sections = (0 until 25).toList().chunked(5)
    LazyVerticalStaggeredGrid(
        columns = StaggeredGridCells.Fixed(3),
        horizontalArrangement = Arrangement.spacedBy(16.dp),
        verticalItemSpacing = 16.dp
    ) {
        sections.forEachIndexed { index, items ->
            item(span = StaggeredGridItemSpan.FullLine) {
                Text(
                    "This is section $index",
                    Modifier.border(1.dp, Color.Gray).height(80.dp).wrapContentSize()
                )
            }
            items(
                items,
                // not required as it is the default
                span = { StaggeredGridItemSpan.SingleLane }
            ) {
                Text(
                    "Item $it",
                    Modifier.border(1.dp, Color.Blue).height(80.dp).wrapContentSize()
                )
            }
        }
    }
}