In Jetpack Compose, when should a screen use LazyColumn instead of a Column, and what does LazyColumn do differently?
answer
- how many items get composed
- a DSL instead of a content lambda
- item, items, stickyHeader
- nesting in the same scroll direction
basics
~20 sUse LazyColumn when the list is long or of unknown length. A Column composes and lays out every child; LazyColumn composes only the items near the viewport and describes them through a LazyListScope DSL of item and items calls.
solid answer
~40 sA `Column` (made scrollable with `Modifier.verticalScroll`) composes, measures and places every child up front, which is fine for a short, fixed form but slow for hundreds of products. `LazyColumn`, `LazyRow` and the lazy grids compose and lay out only the items in or near the viewport, and compose more as the user scrolls. They do not take a `@Composable` content lambda: you describe items through the `LazyListScope` DSL (`item { }`, `items(list) { }`, `itemsIndexed`, `stickyHeader`), and the lazy layout decides when each one is composed. For a product grid use `LazyVerticalGrid` with `GridCells.Adaptive(minSize)` or `GridCells.Fixed(n)`. Do not put a `LazyColumn` with no fixed height inside a `Column` that scrolls vertically: it throws an `IllegalStateException`; add the header as an `item { }` in the same `LazyColumn` instead.
code
kotlin · 16 lines@Composable
fun ProductGrid(products: List<Product>, onOpen: (String) -> Unit) {
LazyVerticalGrid(
columns = GridCells.Adaptive(minSize = 160.dp),
contentPadding = PaddingValues(12.dp),
horizontalArrangement = Arrangement.spacedBy(12.dp),
verticalArrangement = Arrangement.spacedBy(12.dp),
) {
item(span = { GridItemSpan(maxLineSpan) }) {
Text("New arrivals", style = MaterialTheme.typography.titleLarge)
}
items(products) { product ->
ProductCard(product, onClick = { onOpen(product.id) })
}
}
}go deeper
Recall the one-line rule: Column builds every child, LazyColumn builds only what is near the viewport. Know item, items and the grid variants by name.
Explain the LazyListScope DSL, why a lazy list cannot be nested in a same-direction scroll without a size, and how rememberLazyListState exposes and restores the scroll position.
Show production judgment: placeholder sizes so items never measure 0 px, one element per item, release builds with R8 for any performance claim, and adaptive grid cells instead of hand-written breakpoints.
Weigh where a lazy layout is overkill (a short static form) against where a team should make it the default, and how list conventions such as headers as items keep screens consistent.
## Two ways to show a vertical list Jetpack Compose gives you two families of vertical containers: - **`Column`** is an ordinary layout. Every child you emit inside it is composed, measured and placed, whether or not it is on screen. Adding `Modifier.verticalScroll(rememberScrollState())` makes it scroll, but it still builds every child. - **`LazyColumn`** (and its horizontal twin **`LazyRow`**) is a *lazy layout*. It composes and lays out only the items that are visible in its viewport, plus a few prepared ahead of the scroll, and composes more as the user scrolls. Items that scroll far away are disposed or kept for reuse. The official guidance is simple: if the content does not need to scroll, or is a short, fixed set (a settings form with six rows), a `Column` is fine. If you need to show a large number of items, or a list of unknown length (a shop's catalogue, search results, a chat history), a `Column` causes performance problems because all items are composed whether visible or not. Use a lazy layout. ## The DSL: describing items instead of emitting them Most Compose layouts take a `@Composable` content lambda and you call composables inside it. Lazy layouts are different. `LazyColumn` takes a **`LazyListScope.() -> Unit`** block, a small domain-specific language in which you *describe* items; the lazy layout then composes each one when it needs it. | DSL call | What it adds | |---|---| | `item { }` | one item, such as a header or a footer | | `items(count) { index -> }` | `count` items addressed by index | | `items(list) { element -> }` | one item per element (the extension from `androidx.compose.foundation.lazy`) | | `itemsIndexed(list) { index, element -> }` | the same, with the index | | `stickyHeader { }` | a header that sticks to the top while its section scrolls | ```kotlin @Composable fun CatalogueScreen(products: List<Product>) { LazyColumn( contentPadding = PaddingValues(16.dp), verticalArrangement = Arrangement.spacedBy(8.dp), ) { item { PromoBanner() } items(products) { product -> ProductRow(product) } item { CatalogueFooter() } } } ``` `contentPadding` pads the content, not the list itself, so the first item starts 16 dp in yet scrolls to the edge; `Arrangement.spacedBy` adds a gap between items. ## Grids A shopping app usually shows products as a grid. **`LazyVerticalGrid`** and **`LazyHorizontalGrid`** use the same kind of DSL (`LazyGridScope`) and take a `columns` (or `rows`) parameter: - **`GridCells.Fixed(2)`**: exactly two columns. - **`GridCells.Adaptive(minSize = 160.dp)`**: as many columns as fit, each at least 160 dp, with the leftover width shared. This adapts to phones, foldables and tablets without breakpoints in your code. - A full-width header inside a grid uses `item(span = { GridItemSpan(maxLineSpan) }) { }`. `LazyVerticalStaggeredGrid` handles cards of different heights. ## Rules that catch people out 1. **Do not nest scrollables in the same direction without a size.** A `LazyColumn` with no fixed height inside `Column(Modifier.verticalScroll(...))` is measured with an infinite maximum height and throws an `IllegalStateException` ("Vertically scrollable component was measured with an infinity maximum height constraints"). Put the header and footer inside the same `LazyColumn` as `item { }` blocks. Nesting in different directions (a `LazyRow` carousel inside a `LazyColumn`) is allowed, and so is a nested list given a fixed height. 2. **Avoid items that measure 0 px at first.** If images load later and items start at zero height, the lazy layout thinks they all fit and composes every one of them in the first measure. Give items a placeholder size. 3. **One element per item.** Emitting several elements inside one `item { }` makes them compose and measure as one unit and confuses `scrollToItem`; a small divider is the usual exception. 4. **Hoist the list state when you need it.** `val listState = rememberLazyListState()` passed as `state = listState` lets you read `firstVisibleItemIndex` or call `animateScrollToItem(0)` from a coroutine. It is saved with `rememberSaveable`, so the scroll position survives a configuration change. 5. **Measure in a release build.** Lazy layouts can look slow in debug builds; judge their performance with R8 enabled. ## Where this sits Lazy layouts follow the same principles as the View system's recycler-based lists, but you never write an adapter or a view holder. How a client should virtualize and diff a long feed as a cross-platform design is covered in the mobile system design material; this answer is about the Compose APIs that implement it.
- A designer wants a header above a LazyColumn and the whole page to scroll together. How do you build it in Compose?Do not wrap the `LazyColumn` in a `Column` with `verticalScroll`; that throws an `IllegalStateException` because the lazy list is measured with infinite height. Put the header inside the same `LazyColumn` as an `item { Header() }` before `items(products)`, and a footer as a final `item { }`. Everything then scrolls as one list and stays lazy.
- How do you put a horizontal carousel of categories inside a vertical product list in Compose?Emit a `LazyRow` as one `item { }` of the outer `LazyColumn`. Nesting lazy layouts that scroll in different directions is allowed. The carousel's own scroll position lives in its `LazyListState`, which is saveable, and it follows that row through inserts and reorders only if the outer list gives the row a stable key.
- A Column with verticalScroll is just as efficient as LazyColumn for long lists
- LazyColumn takes a normal @Composable content lambda like Column does
- Nesting a LazyColumn inside a vertically scrolling Column is fine without a fixed height
- LazyColumn composes every item once and only skips drawing the hidden ones
- You need a custom adapter class to feed items to LazyColumn