Optimizing Lazy Layouts

Optimizing Lazy Layouts — Keys, contentType, and animateItem()

Lazy layouts compose only what's visible, but two things still cost: re-composition of items that should have been reused (missing key), and per-item allocation that compounds with scroll velocity (missing contentType, modifier chains created inside items { }). Both have a one-line fix. This skill teaches Claude how to apply that fix correctly and to validate that item composables are themselves skippable. Prefetch tuning is a separate concern — see ../configuring-lazy-prefetch/SKILL.md.

When to use this skill

• The developer reports scroll jank, dropped frames, or stutter on a LazyColumn, LazyRow, LazyVerticalGrid, or LazyHorizontalGrid.
• Items lose scroll position, focus, or composition state on insert, remove, or reorder.
• A mixed-type feed (cards + headers + ads + carousels) feels sluggish even though each individual row is lightweight.
• Modifier.animateItem() was added but no animation runs on inserts or removals.
• The compiler report shows item composables as unstable/non-skippable, or @TraceRecomposition shows item composables recomposing on every scroll tick.

When NOT to use this skill

• The bottleneck is the prefetch window (heavy items, high-velocity scroll, want a wider ahead/behind window) → use ../configuring-lazy-prefetch/SKILL.md.
• The item composable itself takes an unstable parameter (List<Foo>, Flow<Foo>, a domain var) → first run ../../stability/diagnosing-compose-stability/SKILL.md and then ../../stability/stabilizing-compose-types/SKILL.md.
• An animation inside an item reads state.value in Composition phase, recomposing the row every frame → use ../../recomposition/deferring-state-reads/SKILL.md.
• Scroll position derivation (e.g. firstVisibleItemIndex == 0) is the hot path → use ../../recomposition/choosing-derivedstateof/SKILL.md.

Prerequisites

• Compose Foundation 1.7+ for Modifier.animateItem() (the GA replacement for the experimental animateItemPlacement).
• Kotlin 2.0.0+ with org.jetbrains.kotlin.plugin.compose applied. Strong Skipping is on by default; non-skippable item composables become amplified at scroll speed.
• A real device + release build for measurement. Skydoves hot take #5: debug builds lie (Live Literals, interpreted mode). See ../../measurement/generating-baseline-profiles/SKILL.md when ready to measure.

Workflow

• 1. Audit every items(...) call. Walk every LazyListScope.items(list), items(count), itemsIndexed(list), and the LazyGridScope equivalents. For each, decide: does each element have a stable identity that outlives a single composition? If yes — and it almost always does — supply key = { it.id } using a server-side stable ID. MUST NOT use the list index, UUID.randomUUID() evaluated per emission, or hashCode() of a mutable object.

// WRONG
LazyColumn { items(snacks) { snack -> SnackRow(snack) } }
// WRONG because: index-based identity → insert/remove discards composition state and breaks animateItem().

// RIGHT
LazyColumn {
    items(
        items = snacks,
        key = { it.id },
        contentType = { it::class },
    ) { snack ->
        SnackRow(snack, Modifier.animateItem())
    }
}

• 2. Add contentType for heterogeneous lists. Lazy layouts maintain a per-type composition cache analogous to RecyclerView's view-type. When item N + 1 has the same contentType as a recycled slot, the cached composition is reused; otherwise it is discarded and rebuilt. For homogeneous lists Compose infers a single content type and contentType is optional. For mixed feeds (cards, headers, ads, carousels, dividers) MUST supply a stable type discriminator.

• 3. Validate item composable stability. Run ../../stability/diagnosing-compose-stability/SKILL.md. If the item composable accepts an unstable parameter, no amount of key/contentType work will help — the row recomposes on every scroll-driven snapshot tick anyway. Fix with ../../stability/stabilizing-compose-types/SKILL.md before tuning further.

• 4. Hoist allocation-heavy values out of the items lambda. The items lambda runs once per item per scroll-driven (re)composition. Painters, color resolutions, shapes, and BorderStroke instances built inside the lambda are reallocated each pass. Hoist constants and remember-based caches above the LazyColumn or to the call site. Modifier chains are themselves cheap because Compose deduplicates them structurally — hoist a Modifier only when profiling proves it matters.

• 5. Add Modifier.animateItem() for visual continuity. Pair with a stable key. The animation runs on inserts, removals, and reorders; without key the animation cannot bind to identity and silently no-ops. The default fade-in / fade-out / placement spring is usually correct; tune with fadeInSpec, fadeOutSpec, placementSpec only when the design system requires it.

• 6. Cache common painters / colors / shapes outside the items block. painterResource(...), MaterialTheme.colorScheme.surface, RoundedCornerShape(...) resolutions on every item composition add up. Hoist to the screen-level composable and pass down, or remember once at the LazyColumn parent.

• 7. Verify with @TraceRecomposition and Layout Inspector. During a controlled scroll, expect each item composable to recompose at most once per real state change — not per scroll tick. Layout Inspector → Recomposition Counts column should plateau, not climb monotonically.