{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

LazyStaggeredGridDslKt

public final class LazyStaggeredGridDslKt


Summary

Public methods

static final void
@Composable
LazyHorizontalStaggeredGrid(
    @NonNull StaggeredGridCells rows,
    @NonNull Modifier modifier,
    @NonNull LazyStaggeredGridState state,
    @NonNull PaddingValues contentPadding,
    boolean reverseLayout,
    @NonNull Arrangement.Vertical verticalArrangement,
    @NonNull Dp horizontalItemSpacing,
    @NonNull FlingBehavior flingBehavior,
    boolean userScrollEnabled,
    @ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content
)

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

static final void
@Composable
LazyVerticalStaggeredGrid(
    @NonNull StaggeredGridCells columns,
    @NonNull Modifier modifier,
    @NonNull LazyStaggeredGridState state,
    @NonNull PaddingValues contentPadding,
    boolean reverseLayout,
    @NonNull Dp verticalItemSpacing,
    @NonNull Arrangement.Horizontal horizontalArrangement,
    @NonNull FlingBehavior flingBehavior,
    boolean userScrollEnabled,
    @ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content
)

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

static final void
<T extends Object> items(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull T[] items,
    Function1<@NonNull item, @NonNull Object> key,
    @NonNull Function1<@NonNull item, Object> contentType,
    Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent
)

Add an array of items to the staggered grid.

static final void
<T extends Object> items(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull List<@NonNull T> items,
    Function1<@NonNull item, @NonNull Object> key,
    @NonNull Function1<@NonNull item, Object> contentType,
    Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent
)

Add a list of items to the staggered grid.

static final void
<T extends Object> itemsIndexed(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull T[] items,
    Function2<@NonNull Integer, @NonNull item, @NonNull Object> key,
    @NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType,
    Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent
)

Add an array of items with index-aware content to the staggered grid.

static final void
<T extends Object> itemsIndexed(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull List<@NonNull T> items,
    Function2<@NonNull Integer, @NonNull item, @NonNull Object> key,
    @NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType,
    Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent
)

Add a list of items with index-aware content to the staggered grid.

Public methods

LazyHorizontalStaggeredGrid

@Composable
public static final void LazyHorizontalStaggeredGrid(
    @NonNull StaggeredGridCells rows,
    @NonNull Modifier modifier,
    @NonNull LazyStaggeredGridState state,
    @NonNull PaddingValues contentPadding,
    boolean reverseLayout,
    @NonNull Arrangement.Vertical verticalArrangement,
    @NonNull Dp horizontalItemSpacing,
    @NonNull FlingBehavior flingBehavior,
    boolean userScrollEnabled,
    @ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content
)

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

Sample:

import androidx.compose.foundation.border
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.lazy.staggeredgrid.LazyHorizontalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.items
import androidx.compose.foundation.lazy.staggeredgrid.itemsIndexed
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

val itemsList = (0..5).toList()
val itemsIndexedList = listOf("A", "B", "C")

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

LazyHorizontalStaggeredGrid(
    rows = StaggeredGridCells.Fixed(3)
) {
    items(itemsList) {
        Text("Item is $it", itemModifier)
    }
    item {
        Text("Single item", itemModifier)
    }
    itemsIndexed(itemsIndexedList) { index, item ->
        Text("Item at index $index is $item", itemModifier)
    }
}

Sample with custom item spans:

import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.lazy.staggeredgrid.LazyHorizontalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridItemSpan
import androidx.compose.foundation.lazy.staggeredgrid.items
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

val sections = (0 until 25).toList().chunked(5)
LazyHorizontalStaggeredGrid(
    rows = StaggeredGridCells.Fixed(3),
    verticalArrangement = Arrangement.spacedBy(16.dp),
    horizontalItemSpacing = 16.dp
) {
    sections.forEachIndexed { index, items ->
        item(span = StaggeredGridItemSpan.FullLine) {
            Text(
                "This is section $index",
                Modifier.border(1.dp, Color.Gray).padding(16.dp).wrapContentSize()
            )
        }
        items(
            items,
            // not required as it is the default
            span = { StaggeredGridItemSpan.SingleLane }
        ) {
            Text(
                "Item $it",
                Modifier.border(1.dp, Color.Blue).width(80.dp).wrapContentSize()
            )
        }
    }
}
Parameters
@NonNull StaggeredGridCells rows

description of the size and number of staggered grid columns.

@NonNull Modifier modifier

modifier to apply to the layout.

@NonNull LazyStaggeredGridState state

state object that can be used to control and observe staggered grid state.

@NonNull PaddingValues contentPadding

padding around the content.

boolean reverseLayout

reverse 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 end.

@NonNull Arrangement.Vertical verticalArrangement

arrangement specifying vertical spacing between items. The item arrangement specifics are ignored for now.

@NonNull Dp horizontalItemSpacing

horizontal spacing between items.

@NonNull FlingBehavior flingBehavior

logic responsible for handling fling.

boolean userScrollEnabled

whether scroll with gestures or accessibility actions are allowed. It is still possible to scroll programmatically through state when userScrollEnabled is set to false

@ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content

a 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.

LazyVerticalStaggeredGrid

@Composable
public static final void LazyVerticalStaggeredGrid(
    @NonNull StaggeredGridCells columns,
    @NonNull Modifier modifier,
    @NonNull LazyStaggeredGridState state,
    @NonNull PaddingValues contentPadding,
    boolean reverseLayout,
    @NonNull Dp verticalItemSpacing,
    @NonNull Arrangement.Horizontal horizontalArrangement,
    @NonNull FlingBehavior flingBehavior,
    boolean userScrollEnabled,
    @ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content
)

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

Sample:

import androidx.compose.foundation.border
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.lazy.staggeredgrid.LazyVerticalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.items
import androidx.compose.foundation.lazy.staggeredgrid.itemsIndexed
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

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))
    }
}

Sample with custom item spans:

import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.foundation.lazy.staggeredgrid.LazyVerticalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridItemSpan
import androidx.compose.foundation.lazy.staggeredgrid.items
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

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()
            )
        }
    }
}
Parameters
@NonNull StaggeredGridCells columns

description of the size and number of staggered grid columns.

@NonNull Modifier modifier

modifier to apply to the layout.

@NonNull LazyStaggeredGridState state

state object that can be used to control and observe staggered grid state.

@NonNull PaddingValues contentPadding

padding around the content.

boolean reverseLayout

reverse 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.

@NonNull Dp verticalItemSpacing

vertical spacing between items.

@NonNull Arrangement.Horizontal horizontalArrangement

arrangement specifying horizontal spacing between items. The item arrangement specifics are ignored for now.

@NonNull FlingBehavior flingBehavior

logic responsible for handling fling.

boolean userScrollEnabled

whether scroll with gestures or accessibility actions are allowed. It is still possible to scroll programmatically through state when userScrollEnabled is set to false

@ExtensionFunctionType @NonNull Function1<@NonNull LazyStaggeredGridScopeUnit> content

a 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.

items

public static final void <T extends Object> items(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull T[] items,
    Function1<@NonNull item, @NonNull Object> key,
    @NonNull Function1<@NonNull item, Object> contentType,
    Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent
)

Add an array of items to the staggered grid.

Parameters
@NonNull T[] items

a data array to present

Function1<@NonNull item, @NonNull Object> key

a factory of stable and unique keys representing the item. The key MUST be saveable via Bundle on Android. If set to null (by default), the position of the item will be used as a key instead. Using the same key for multiple items in the staggered grid is not allowed.

When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull Function1<@NonNull item, Object> contentType

a factory of content types representing the item. Content for item of the same type can be reused more efficiently. null is a valid type as well and items of such type will be considered compatible.

Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span

a factory of custom spans for this item. Spans configure how many lanes defined by StaggeredGridCells the item will occupy. By default each item will take one lane.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent

composable content displayed by the provided item

items

public static final void <T extends Object> items(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull List<@NonNull T> items,
    Function1<@NonNull item, @NonNull Object> key,
    @NonNull Function1<@NonNull item, Object> contentType,
    Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent
)

Add a list of items to the staggered grid.

Parameters
@NonNull List<@NonNull T> items

a data list to present

Function1<@NonNull item, @NonNull Object> key

a factory of stable and unique keys representing the item. The key MUST be saveable via Bundle on Android. If set to null (by default), the position of the item will be used as a key instead. Using the same key for multiple items in the staggered grid is not allowed.

When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull Function1<@NonNull item, Object> contentType

a factory of content types representing the item. Content for item of the same type can be reused more efficiently. null is a valid type as well and items of such type will be considered compatible.

Function1<@NonNull item, @NonNull StaggeredGridItemSpan> span

a factory of custom spans for this item. Spans configure how many lanes defined by StaggeredGridCells the item will occupy. By default each item will take one lane.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull LazyStaggeredGridItemScope, @NonNull item, Unit> itemContent

composable content displayed by the provided item

itemsIndexed

public static final void <T extends Object> itemsIndexed(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull T[] items,
    Function2<@NonNull Integer, @NonNull item, @NonNull Object> key,
    @NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType,
    Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent
)

Add an array of items with index-aware content to the staggered grid.

Parameters
@NonNull T[] items

a data array to present

Function2<@NonNull Integer, @NonNull item, @NonNull Object> key

a factory of stable and unique keys representing the item. The key MUST be saveable via Bundle on Android. If set to null (by default), the position of the item will be used as a key instead. Using the same key for multiple items in the staggered grid is not allowed.

When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType

a factory of content types representing the item. Content for item of the same type can be reused more efficiently. null is a valid type as well and items of such type will be considered compatible.

Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span

a factory of custom spans for this item. Spans configure how many lanes defined by StaggeredGridCells the item will occupy. By default each item will take one lane.

@Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent

composable content displayed given item and index

itemsIndexed

public static final void <T extends Object> itemsIndexed(
    @NonNull LazyStaggeredGridScope receiver,
    @NonNull List<@NonNull T> items,
    Function2<@NonNull Integer, @NonNull item, @NonNull Object> key,
    @NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType,
    Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span,
    @Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent
)

Add a list of items with index-aware content to the staggered grid.

Parameters
@NonNull List<@NonNull T> items

a data list to present

Function2<@NonNull Integer, @NonNull item, @NonNull Object> key

a factory of stable and unique keys representing the item. The key MUST be saveable via Bundle on Android. If set to null (by default), the position of the item will be used as a key instead. Using the same key for multiple items in the staggered grid is not allowed.

When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull Function2<@NonNull Integer, @NonNull item, Object> contentType

a factory of content types representing the item. Content for item of the same type can be reused more efficiently. null is a valid type as well and items of such type will be considered compatible.

Function2<@NonNull Integer, @NonNull item, @NonNull StaggeredGridItemSpan> span

a factory of custom spans for this item. Spans configure how many lanes defined by StaggeredGridCells the item will occupy. By default each item will take one lane.

@Composable @ExtensionFunctionType @NonNull Function3<@NonNull LazyStaggeredGridItemScope, @NonNull Integer, @NonNull item, Unit> itemContent

composable content displayed given item and index