# LazyVerticalStaggeredGrid

Common/All

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyVerticalStaggeredGrid.composable#LazyVerticalStaggeredGrid(androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells,androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.staggeredgrid.LazyStaggeredGridState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,kotlin.Function1)( columns: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/StaggeredGridCells, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState, contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues, reverseLayout: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, verticalItemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, horizontalArrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Horizontal, flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior, userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect?, content: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Vertical staggered grid layout that composes and lays out only items currently visible on screen. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyVerticalStaggeredGrid.composable#LazyVerticalStaggeredGrid(androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells,androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.staggeredgrid.LazyStaggeredGridState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,androidx.compose.foundation.lazy.layout.LazyLayoutCacheWindow,kotlin.Function1)( columns: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/StaggeredGridCells, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState, contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues, reverseLayout: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, verticalItemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, horizontalArrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Horizontal, flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior, userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect?, cacheWindow: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/layout/LazyLayoutCacheWindow, content: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Vertical staggered grid layout that composes and lays out only items currently visible on screen. | Cmn |

## Functions

### LazyVerticalStaggeredGrid

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridDsl.kt+function:LazyVerticalStaggeredGrid)

```
@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,
    overscrollEffect: OverscrollEffect? = rememberOverscrollEffect(),
    content: LazyStaggeredGridScope.() -> Unit
): Unit
```

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

Sample:

```kotlin
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.material3.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:

```kotlin
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.material3.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 |
|---|---|
| `columns: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/StaggeredGridCells` | description of the size and number of staggered grid columns. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | modifier to apply to the layout. |
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState = rememberLazyStaggeredGridState()` | state object that can be used to control and observe staggered grid state. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues = PaddingValues(0.dp)` | padding around the content. |
| `reverseLayout: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | reverse the direction of scrolling and layout. When `true`, items are laid out in the reverse order and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState#firstVisibleItemIndex()` == 0 means that grid is scrolled to the bottom. |
| `verticalItemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | vertical spacing between items. |
| `horizontalArrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Horizontal = Arrangement.spacedBy(0.dp)` | arrangement specifying horizontal spacing between items. The item arrangement specifics are ignored for now. |
| `flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior = ScrollableDefaults.flingBehavior()` | logic responsible for handling fling. |
| `userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | whether scroll with gestures or accessibility actions are allowed. It is still possible to scroll programmatically through state when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/package-summary#LazyVerticalStaggeredGrid(androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells,androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.staggeredgrid.LazyStaggeredGridState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,kotlin.Function1)` is set to false |
| `overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect? = rememberOverscrollEffect()` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect` that will be used to render overscroll for this layout. Note that the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect#node()` will be applied internally as well - you do not need to use Modifier.overscroll separately. |
| `content: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | a lambda describing the staggered grid content. Inside this block you can use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope#items(kotlin.Int,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function2)` to present list of items or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope#item(kotlin.Any,kotlin.Any,androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridItemSpan,kotlin.Function1)` for a single one. |

### LazyVerticalStaggeredGrid

Cmn Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridDsl.kt+function:LazyVerticalStaggeredGrid)

```
@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,
    overscrollEffect: OverscrollEffect? = rememberOverscrollEffect(),
    cacheWindow: LazyLayoutCacheWindow = LazyLayoutCacheWindow(
            behindFraction = 0f,
            aheadFraction = 0.5f,
            isNonScrollCachingEnabled = false,
        ),
    content: LazyStaggeredGridScope.() -> Unit
): Unit
```

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

Sample:

```kotlin
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.material3.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:

```kotlin
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.material3.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())
        }
    }
}
```

Sample with custom cache window:

```kotlin
import androidx.compose.foundation.lazy.layout.LazyLayoutCacheWindow
import androidx.compose.foundation.lazy.staggeredgrid.LazyVerticalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.items
import androidx.compose.material3.Text

val itemsList = (0..100).toList()

LazyVerticalStaggeredGrid(
    columns = StaggeredGridCells.Fixed(3),
    cacheWindow = LazyLayoutCacheWindow(aheadFraction = 0.5f, behindFraction = 0.2f),
) {
    items(itemsList) { item -> Text("Item $item") }
}
```

| Parameters |
|---|---|
| `columns: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/StaggeredGridCells` | description of the size and number of staggered grid columns. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | modifier to apply to the layout. |
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState = rememberLazyStaggeredGridState()` | state object that can be used to control and observe staggered grid state. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues = PaddingValues(0.dp)` | padding around the content. |
| `reverseLayout: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | reverse the direction of scrolling and layout. When `true`, items are laid out in the reverse order and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridState#firstVisibleItemIndex()` == 0 means that grid is scrolled to the bottom. |
| `verticalItemSpacing: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | vertical spacing between items. |
| `horizontalArrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Horizontal = Arrangement.spacedBy(0.dp)` | arrangement specifying horizontal spacing between items. The item arrangement specifics are ignored for now. |
| `flingBehavior: https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/FlingBehavior = ScrollableDefaults.flingBehavior()` | logic responsible for handling fling. |
| `userScrollEnabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | whether scroll with gestures or accessibility actions are allowed. It is still possible to scroll programmatically through state when `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/package-summary#LazyVerticalStaggeredGrid(androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells,androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.staggeredgrid.LazyStaggeredGridState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,androidx.compose.foundation.lazy.layout.LazyLayoutCacheWindow,kotlin.Function1)` is set to false |
| `overscrollEffect: https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect? = rememberOverscrollEffect()` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect` that will be used to render overscroll for this layout. Note that the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/OverscrollEffect#node()` will be applied internally as well - you do not need to use `Modifier.overscroll` separately. |
| `cacheWindow: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/layout/LazyLayoutCacheWindow = LazyLayoutCacheWindow( behindFraction = 0f, aheadFraction = 0.5f, isNonScrollCachingEnabled = false, )` | specifies the size of the ahead and behind window to be used as per `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/layout/LazyLayoutCacheWindow`. |
| `content: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | a lambda describing the staggered grid content. Inside this block you can use `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope#items(kotlin.Int,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function2)` to present list of items or `https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/staggeredgrid/LazyStaggeredGridScope#item(kotlin.Any,kotlin.Any,androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridItemSpan,kotlin.Function1)` for a single one. |