Lists with LazyColumn & LazyRow

What you'll learn

Almost every app shows a list — chats, contacts, a feed, search results. Rendering those efficiently is a solved problem in Compose, but only if you reach for the right tool. This module is about the lazy list composables and the one detail (keys) that keeps them fast and correct.

By the end you'll be able to:

• Explain why LazyColumn beats a scrolling Column for real data
• Build vertical and horizontal lists
• Use item, items, and itemsIndexed
• Add keys for correctness and performance, and build grids

Why lazy lists

A regular Column composes all its children immediately, whether they're on screen or not. For ten items that's fine; for a thousand it's a disaster — slow startup and wasted memory:

// DON'T do this for long or dynamic lists:
Column(Modifier.verticalScroll(rememberScrollState())) {
    items.forEach { item ->
        ItemRow(item)   // every item is composed up front — slow, memory-hungry
    }
}

A lazy list only composes the items that are currently visible (plus a small buffer), and recycles them as you scroll — the same idea as RecyclerView, but with almost no boilerplate. Use a scrolling Column only for a handful of known items; reach for LazyColumn for anything long or data-driven.

LazyColumn & LazyRow

LazyColumn scrolls vertically and LazyRow horizontally. Instead of writing children directly, you describe content inside a special scope using items:

LazyColumn {
    items(contacts) { contact ->
        ContactRow(contact)          // composed only when scrolled into view
    }
}

item, items & itemsIndexed

Inside a lazy list you have three building blocks. Use item { } for a single one-off (a header), items(list) to emit one composable per element, and itemsIndexed(list) when you also need each element's position:

LazyColumn {
    item {                                   // a single, one-off item
        Text("Contacts", style = MaterialTheme.typography.headlineSmall)
    }
    items(contacts) { contact ->             // many items from a list
        ContactRow(contact)
    }
    itemsIndexed(contacts) { index, contact ->   // when you need the position
        Text("${index + 1}. ${contact.name}")
    }
}

Keys — the detail that matters

By default Compose identifies items by their position in the list. That breaks down when the list changes — insert an item at the top and every row shifts by one, so Compose thinks every row changed and needlessly recomposes them (and any per-item state, like an expanded card, jumps to the wrong row). Give each item a stable, unique key and Compose can track items by identity across changes:

LazyColumn {
    items(
        items = contacts,
        key = { contact -> contact.id },   // stable, unique identity per item
    ) { contact ->
        ContactRow(contact)
    }
}

Grids

For a gallery-style grid, use LazyVerticalGrid (or LazyHorizontalGrid). You choose the columns with GridCells.Fixed(n) for a set count, or GridCells.Adaptive(minSize) to let Compose fit as many columns as will fit the width — great for responsive layouts across phone and tablet:

LazyVerticalGrid(
    columns = GridCells.Fixed(2),          // or GridCells.Adaptive(minSize = 120.dp)
    contentPadding = PaddingValues(12.dp),
    horizontalArrangement = Arrangement.spacedBy(12.dp),
    verticalArrangement = Arrangement.spacedBy(12.dp),
) {
    items(photos) { photo -> PhotoCard(photo) }
}

Recap & quick check

Your lists are fast and correct. Now let's make everything beautiful and consistent with Material Design 3.