Optimizing Lazy Layouts

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 87cfb886f00d · 16 Oct 2026Report an issue or request a re-scan

• Publisherskydoves GitHub userOwner of the repository this skill is read from
• Source folderskydoves/compose-performance-skills/lists/optimizing-lazy-layoutsThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict87cfb886f00dA new audit runs when the source changes
• Repository statusNot archivedLast push 121 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use this skill to fix scroll jank, lost item state, and broken animateItem() animations in LazyColumn, LazyRow, LazyVerticalGrid, and LazyHorizontalGrid. Covers stable item keys, contentType for mixed-type feeds,…

---
name: optimizing-lazy-layouts
description: Use this skill to fix scroll jank, lost item state, and broken animateItem() animations in LazyColumn, LazyRow, LazyVerticalGrid, and LazyHorizontalGrid. Covers stable item keys, contentType for mixed-type feeds, Modifier.animateItem() requirements, hoisting modifier chains and painters out of the items lambda, and validating item composable stability. Use when the developer mentions LazyColumn jank, dropped frames while scrolling, items losing scroll state on insert/remove/reorder, mixed feeds of cards/headers/ads feeling sluggish, animateItem() not animating, RecyclerView view-type analog, key parameter, or contentType parameter. The prefetch-window tuning lives in a sibling skill.
license: Apache-2.0. See LICENSE for complete terms.
metadata:
  author: Jaewoong Eum (skydoves)
  keywords:
  - jetpack-compose
  - performance
  - lazy-column
  - lazy-row
  - lazy-grid
  - scroll-jank
  - item-key
  - content-type
  - animate-item
---

# 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.

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

```kotlin
// 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 sys

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/skydoves/compose-performance-skills
git -C compose-performance-skills checkout 87cfb886f00d

Works in

1. 2026-10-16
   ✓SAFE B 89 / 100

   first audit · source 87cfb886f00d

Questions about Optimizing Lazy Layouts

• github.com/skydoves/compose-performance-skills/tree/main/lists/o — the audited source at commit 87cfb886f00d and every finding aboveObserved · 16 Oct 2026

Spotted something wrong? Report a correction · Methodology