Lazy Layouts: Lists, Grids and Scrolling Performance

In lesson 21 you built a list with LazyColumn and a grid with LazyVerticalGrid, and that took you a long way. This lesson goes deeper, because scrolling lists are where apps feel fast or feel broken. A list that stutters, loses its scroll position, resets an expanded item when you add a row, or jumps when images load is a list built without understanding keys, content types and state.

This lesson covers the Lazy layouts item of Pathway 2 of the Jetpack Compose for Android developers programme (https://developer.android.com/courses/pathways/jetpack-compose-for-android-developers-2).

By the end you will be able to:

• Choose among LazyColumn, LazyRow, LazyVerticalGrid, LazyHorizontalGrid and staggered grids.
• Build lists from mixed content with item { }, items { }, itemsIndexed and stickyHeader.
• Explain what keys do and choose good ones.
• Use content types to help Compose reuse composables.
• Control and observe scrolling with LazyListState.
• Animate insertions, removals and reordering with animateItem().
• Avoid the classic crashes: nested scrolling and zero-size items.
• Apply the main performance rules, and measure.

Big idea: a lazy list is a window onto a large data set. Keys give each item an identity so that state, animations and scroll position follow the right item when the data changes.

• Basic LazyColumn and LazyVerticalGrid (lesson 21).
• Recomposition and the three phases (lesson 37).
• State hoisting and immutable data classes (lesson 24).
• Layouts and modifiers (lesson 38).

A normal Column composes all its children. A LazyColumn composes only the items visible plus a small buffer, and disposes of items that scroll far away.

data: [item 0][item 1][item 2] ... [item 998][item 999]

screen window:       +--------+
                     | item 40|   <- composed
                     | item 41|   <- composed
                     | item 42|   <- composed
                     +--------+
 composed in a small buffer above and below; everything else does not exist as UI.

Three consequences you must keep in mind:

1. Item state is not kept when an item scrolls away, unless it is stored with rememberSaveable (which survives item disposal in a lazy list) or, better, in your data/ViewModel.
2. Items are identified by position unless you give a key. If the data changes (an item is inserted at the top), position-based identity makes every item below look as if its content changed.
3. The lazy DSL (LazyListScope) is not composable code. Inside LazyColumn { ... } you call item { } and items { }; you cannot call Text(...) directly there. The lambda you pass to item { } is composable.

The lazy family

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
@Composable
fun MixedList(favourites: List<String>, recent: List<String>) {
 LazyColumn(
 contentPadding = PaddingValues(16.dp),
 verticalArrangement = Arrangement.spacedBy(8.dp)
 ) {
 item { Text("Favourites") } // one item
 items(favourites) { name -> Text(name) } // one item per element
 item { Text("Recent") }
 itemsIndexed(recent) { index, name -> Text("${index + 1}. $name") }
 item { Text("End of list") }
 }
}

The "mixed list" pattern, with headers and several kinds of rows in one scrolling container, is why you should have a single LazyColumn for a whole screen instead of nesting scrolling containers (see the nesting section).

Sticky headers

stickyHeader keeps the current section header pinned to the top while its section scrolls. It is currently marked experimental in many Foundation versions:

import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.MaterialTheme
@OptIn(ExperimentalFoundationApi::class)
@Composable
fun ContactsList(grouped: Map<Char, List<String>>) {
 LazyColumn {
 grouped.forEach { (initial, names) ->
 stickyHeader {
 Text(
 initial.toString(),
 modifier = Modifier
 .fillMaxWidth()
 .background(MaterialTheme.colorScheme.surfaceVariant)
 .padding(8.dp)
 )
 }
 items(names, key = { it }) { name ->
 Text(name, Modifier.padding(16.dp))
 }
 }
 }
}

Give the sticky header an opaque background, otherwise the items scrolling underneath show through it. (If your Compose version no longer needs the opt-in, the compiler will warn that it is unnecessary; remove it.)

The problem

Imagine a list of tasks, each with a checkbox whose state is held inside the row with remember:

data class Task(val id: Int, val title: String)
@Composable
fun TaskRow(task: Task) {
 var done by rememberSaveable { mutableStateOf(false) }
 Row {
 Checkbox(checked = done, onCheckedChange = { done = it })
 Text(task.title)
 }
}
LazyColumn {
 items(tasks) { task -> TaskRow(task) } // no key
}

Check "Buy rice" (position 0), then add a new task at the top. Without keys, Compose identifies rows by position. The row at position 0 keeps its done = true state but now displays the new task, so the new task appears ticked while "Buy rice" (now position 1) is not. The state stuck to the slot, not the item.

The fix

LazyColumn {
 items(tasks, key = { it.id }) { task -> TaskRow(task) }
}

With key = { it.id }, state and animation follow the id. Insert, delete or reorder, and each row keeps its own state.

Rules for keys:

In Room entities, the primary key is the natural key (lesson 34). For static lists that never change, keys matter less, but adding them is a good habit.

When a list mixes different kinds of rows (headers, photos, ads), Compose can reuse the composition of an item that scrolled off for a new item that scrolls on, if they are the same type of item. By default it assumes all items are the same type. Tell it explicitly:

sealed interface Row {
 data class Header(val title: String) : Row
 data class Product(val id: Int, val name: String) : Row
}
LazyColumn {
 items(
 items = rows,
 key = { row ->
 when (row) {
 is Row.Header -> "header_${row.title}"
 is Row.Product -> "product_${row.id}"
 }
 },
 contentType = { row ->
 when (row) {
 is Row.Header -> "header"
 is Row.Product -> "product"
 }
 }
 ) { row ->
 when (row) {
 is Row.Header -> HeaderRow(row.title)
 is Row.Product -> ProductRow(row)
 }
 }
}

Notice the two string prefixes in the keys, which keep a header named "42" from clashing with a product with id 42. contentType is purely a performance hint: reusing a compatible composition is cheaper than creating a different one. It is worth adding to any list with clearly different row layouts; it does nothing for single-type lists.

You met LazyVerticalGrid with GridCells.Fixed and GridCells.Adaptive in lesson 21. Two more capabilities:

Items that span columns

import androidx.compose.foundation.lazy.grid.GridItemSpan
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.compose.foundation.lazy.grid.items
LazyVerticalGrid(columns = GridCells.Adaptive(minSize = 140.dp)) {
 item(span = { GridItemSpan(maxLineSpan) }) { // a full-width header across all columns
 Text("Photos", style = MaterialTheme.typography.titleLarge)
 }
 items(photos, key = { it.id }) { PhotoTile(it) }
}

maxLineSpan is "all columns of this row", however many there are.

Staggered grids

When items have different heights (cards with varying text), a normal grid leaves gaps. A staggered grid packs each item under the shortest column:

import androidx.compose.foundation.lazy.staggeredgrid.LazyVerticalStaggeredGrid
import androidx.compose.foundation.lazy.staggeredgrid.StaggeredGridCells
import androidx.compose.foundation.lazy.staggeredgrid.items
LazyVerticalStaggeredGrid(
 columns = StaggeredGridCells.Adaptive(minSize = 160.dp),
 contentPadding = PaddingValues(8.dp),
 horizontalArrangement = Arrangement.spacedBy(8.dp),
 verticalItemSpacing = 8.dp
) {
 items(notes, key = { it.id }) { note -> NoteCard(note) }
}

(Note verticalItemSpacing rather than verticalArrangement.) Use staggered grids for notes, photos of mixed aspect ratio and Pinterest-style feeds.

LazyListState holds the scroll position and lets you read it or move it:

import androidx.compose.foundation.lazy.rememberLazyListState
import androidx.compose.runtime.derivedStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import kotlinx.coroutines.launch
@Composable
fun MessagesScreen(messages: List<Message>) {
 val listState = rememberLazyListState()
 val scope = rememberCoroutineScope()
 // true when the first visible item is not at the very top
 val showScrollToTop by remember {
 derivedStateOf { listState.firstVisibleItemIndex > 0 }
 }
 Box {
 LazyColumn(state = listState) {
 items(messages, key = { it.id }) { MessageRow(it) }
 }
 if (showScrollToTop) {
 FloatingActionButton(
 onClick = { scope.launch { listState.animateScrollToItem(0) } },
 modifier = Modifier.align(Alignment.BottomEnd).padding(16.dp)
 ) { Icon(Icons.Filled.KeyboardArrowUp, contentDescription = "Back to top") }
 }
 }
}

Important details:

• rememberLazyListState() creates and remembers the state; it uses rememberSaveable internally so the scroll position survives rotation.
• animateScrollToItem(index) and scrollToItem(index) are suspend functions: launch them from a coroutine scope (rememberCoroutineScope, lesson 28).
• derivedStateOf is the key trick: firstVisibleItemIndex changes on almost every scroll frame, but showScrollToTop changes only when the answer flips between true and false. Wrapping the calculation in derivedStateOf makes the composable recompose only when the result changes, not on every scroll pixel. Reading listState.firstVisibleItemIndex > 0 directly in the composable would recompose on every index change.
• Other useful properties: firstVisibleItemScrollOffset, layoutInfo.visibleItemsInfo, canScrollForward, isScrollInProgress.

To react to scroll events (for example, loading the next page), use a flow:

LaunchedEffect(listState) {
 snapshotFlow { listState.layoutInfo.visibleItemsInfo.lastOrNull()?.index }
 .filterNotNull()
 .distinctUntilChanged()
 .collect { lastVisible ->
 if (lastVisible >= messages.size - 5) onLoadMore()
 }
}

snapshotFlow turns Compose state reads into a Flow (lessons 33 and 55). This is the standard way to implement infinite scrolling: when the user is within five items of the end, ask the ViewModel for another page (lesson 62 covers Paging 3, which automates this).

Item animations

LazyColumn {
 items(tasks, key = { it.id }) { task ->
 TaskRow(task, modifier = Modifier.animateItem())
 }
}

Modifier.animateItem() animates placement (when an item moves because others were added or removed), fade-in and fade-out. It requires keys, because it needs to know which item is which. On older Compose versions the modifier is called animateItemPlacement() and is experimental; check which your version provides.

Never nest same-direction scrolling

// CRASH: a vertically scrolling LazyColumn inside a vertically scrolling Column
Column(Modifier.verticalScroll(rememberScrollState())) {
 Text("Header")
 LazyColumn { items(100) { Text("Row $it") } }
}

This throws Vertically scrollable component was measured with an infinity maximum height constraints. The Column gives its child unlimited height, and a lazy list cannot decide how many items to compose in an infinite space. Fixes, in order of preference:

1. One lazy container. Put the header as the first item { } of the LazyColumn.
2. Give the inner list a fixed or bounded height (Modifier.height(300.dp)), when a small inner scroller is intentional.
3. For a short, known-size list, use a plain Column (no laziness) inside the scrolling Column.

Different directions are fine: a LazyRow carousel inside a LazyColumn item is a common, supported pattern.

Never create 0-pixel items

If an item has no content on first composition (for example, an image that loads asynchronously with no size set), its height is 0. The list may then compose hundreds of items at once to fill the screen, which defeats laziness and lags badly. Always give items a minimum size (Modifier.heightIn(min = 72.dp), aspectRatio, or a placeholder of the right height) while their content loads.

Measure first (Layout Inspector recomposition counts and the profiler, lessons 44 and 59), then apply the relevant rules:

A very important point: always judge scrolling performance in a release (or benchmark) build, ideally on a real, modest phone. Debug builds include checks that make Compose look janky even when your code is fine.

Mistake #1: No keys on a list that changes. What happens: state attaches to the wrong item; animations look wrong. The fix: a stable, unique key based on identity.

Mistake #2: Using the list index as the key. What happens: the same problem as no key. The fix: use the item id.

Mistake #3: Duplicate keys. Symptom: Key ... was already used. The fix: make keys unique, prefixing by type if you mix item kinds.

Mistake #4: A lazy list inside a vertical scroll. Symptom: the infinite-height crash. The fix: a single lazy container.

Mistake #5: Zero-height items on first composition. What happens: hundreds of items composed at once. The fix: a minimum size or placeholder.

Mistake #6: Expensive work in the item body. What happens: jank while scrolling. The fix: precompute in the ViewModel, or remember.

Mistake #7: Reading firstVisibleItemIndex directly for UI conditions. What happens: recomposition on every index change. The fix: derivedStateOf.

Mistake #8: Item state in remember inside the row. What happens: it is lost when the row scrolls away. The fix: keep it in your data or use rememberSaveable with proper keys.

Mistake #9: Judging performance in a debug build. What happens: you "fix" problems that do not exist. The fix: test a release build.

Mistake #10: Forgetting contentPadding. What happens: the first and last items stick to the edges, and a bottom FAB hides the last row. The fix: contentPadding (not outer padding), so items scroll through the padded area.

Question 1. Why is LazyColumn more efficient than Column with a loop?

Question 2. What problem do keys solve?

Question 3. What is contentType for?

Question 4. Why is derivedStateOf useful with scroll state?

Question 5. Why does a LazyColumn inside a vertically scrolling Column crash?

Go deeper: official resources

• Jetpack Compose for Android developers, Pathway 2: Layouts, theming and animation
• Jetpack Compose course page
• Jetpack Compose performance codelab
• Jetpack Compose layouts codelab