jetpack-compose-performance

---

name: jetpack-compose-performance description: Diagnose and optimize Android Jetpack Compose UI code. Use this skill when analyzing performance bottlenecks of existing code to minimize recomposition overhead and prevent dropped frames and UI lag. license: Complete terms in LICENSE.txt metadata: author: Google LLC last-updated: '2026-10-13' keywords:

• Jetpack Compose
• performance
• UI development
• optimization
• recomposition
• lazy layouts
• graphics
• stability
• memory
• allocation
• jank
• rendering
• state computation
• state derivation
• snapshotFlow
• produceState
• derivedStateOf
• computedStateOf
• sharedElement
• sharedBounds
• CompositionLocal

---

Foundational prerequisites

Before micro-optimizing composables, ensure standard production flags are in place:

1. Release Build: Never profile or benchmark debuggable builds; ART runtime verification severely degrades performance.
2. R8 Minification: Keep R8 enabled to optimize bytecode and coroutine dispatch.
3. Baseline Profiles: Generate baseline profiles for critical user journeys (cold start, key scrolling feeds) so the ART VM pre-compiles and preloads classes ahead of time.

Optimization audit workflow

1. Exhaustive Scan : Scan the target code against all 7 core categories in the following sections. Evaluate every @Composable function, modifier chain, and lazy-layout data model against all checklist rules rather than stopping after the first issue found.
2. Mandatory Reference Read Before Flagging or Editing : Whenever a file matches a rule in Categories 1--7, you MUST open and read the corresponding references/*.md file for the approved fix pattern and full scope guards before reporting a finding or editing code. Never rely on the summary bullets alone to write fixes.

1. State, snapshots, and stability (references/state-and-stability.md)

MANDATORY : Before flagging or fixing any issue in this category, you MUST read references/state-and-stability.md.

• Phase Deferral (Lambdas) : Wrap frequently changing state reads in lambdas (such as Modifier.offset or Modifier.graphicsLayer) so reads occur in Layout or Draw phase rather than Composition.
• Prohibit Backwards Writes (Verify Read-Before-Write Order) : Never modify state in a later phase or after it has already been read in the same composition pass (Read -> Write, or Composition Read -> Layout or Draw Write). Prevent backwards writes across phases to avoid first-frame popping, jank, and infinite recomposition loops (Backwards Write). Do not flag a state assignment at the start of a composable (Write -> Read or Composition Write -> Draw Read) as a backwards write---a backwards write strictly requires a read of that state to precede the write.
• Avoid Redundant State Wrapping in Composition (Write -> Read) : Do not wrap synchronous values in remember { mutableStateOf(...) } only to overwrite them immediately at the top of composition before reading them (for example, var path by remember { mutableStateOf(Path()) }; path = viewModel.getPath()). While not a backwards write, this adds unnecessary slot table and MutableState snapshot overhead (and risks becoming a backwards write if a read is later added preceding the assignment); use a plain local val or read the value directly inside the target phase (such as Modifier.drawWithCache).
• Explicit remember Keys & Slot Overhead : Always pass all input variables and composable parameters referenced inside remember as calculation keys. Remember that remember stores keys + 1 objects in the slot table and checks key equality on every recomposition; only remember when allocations are heavy or identity must be preserved. Do not pass snapshot state values/properties (e.g. state.value) as keys when wrapping derivedStateOf (passing the State instance itself is fine if the instance reference can change).
• computedStateOf vs derivedStateOf (Compose 1.13+) : On Compose 1.13+, use computedStateOf for simple condition checks and filtered state from fast-changing inputs (such as scrollState.value > 0), which provides significantly faster invalidation than derivedStateOf (on Compose < 1.13, use remember { derivedStateOf { ... } }). Reserve derivedStateOf for heavy calculations that benefit from multi-read caching, or trivial calculations read frequently enough per composition (roughly 10 / numberOfStatesReadPerCalculation times without invalidating between reads) to make up for the invalidation cost.
• Synchronous State Derivation : Audit for asynchronous produceState + snapshotFlow blocks observing Compose states (such as scroll positions or collection sizes); replace them with synchronous remember { derivedStateOf { ... } } (or computedStateOf on Compose 1.13+).
• Trivial Primitives : Prefer plain custom Kotlin getters (get()) over derivedStateOf or computedStateOf for simple boolean expressions and property lookups.
• Collection State Tracking : Back whole-list updates with standard mutableListOf() and mutableStateOf(list, neverEqualPolicy()) with load-bearing assignments instead of mutableStateListOf().
• Snapshot Collections : Use SnapshotStateList.toList() for repeated queries or iterations to avoid per-element read observation overhead.
• Repeated State Reads : Extract repeated Compose State property reads into a local variable at the top of the block.
• State in Setters : Avoid reading Compose State inside custom property setters; use a raw backing field when triggering change side-effects and batch multi-property updates.
• Stability & Skipping Trade-Offs (Skipping Isn't Free) : Do not fixate on stability or treat @Immutable, @Stable, or ImmutableList as default solutions. Skipping a composable is not free: each parameter is stored in the slot table as if remembered, and all inputs must be compared on recomposition. Strong Skipping Mode already skips composables with unstable parameters (including standard kotlin.collections.List) when instance equality (===) matches. Annotating models or using ImmutableList forces structural equality (.equals()), which can be significantly more expensive than recomposition itself for large collections or complex classes.
• Never Add @Stable, @Immutable, or ImmutableList to Collection Models : When writing or optimizing code, never add @Immutable or @Stable to models containing collections (List, Set, Map), and never recommend replacing kotlin.collections.List<T> with ImmutableList<T> (or adding ImmutableList to stability_config.txt). Calling O(N) .equals() on collections on every recomposition pass is more expensive than O(1) instance equality (===) under Strong Skipping Mode.
• Scope Guard for Removing Existing @Stable / @Immutable Annotations (Large Lazy Datasets Only) :
  • When to Remove : Only recommend removing existing @Stable or @Immutable annotations from data models when both conditions are met: (1) the model is used within a lazy layout (LazyColumn, LazyRow, LazyGrid, Pager, ScalingLazyColumn) as the input feed or item model, and (2) it contains a large dataset or deep nested collection hierarchy (e.g., feed streams, large lists of tags/items, or multi-level nested lists like Post with List<Paragraph> and List<Markup>), where recursive O(N) .equals() checks degrade scrolling and recomposition performance.
  • When to Leave Untouched : For all other existing @Stable, @Immutable, or ImmutableList usages in a codebase---such as non-lazy UI models, standalone components, or models with small/bounded collections (e.g., a card with a few badges, thumbnails, or metadata rows) where dataset size is small or unknown---leave the existing annotations untouched and do not flag them . Never blindly grep and flag all @Stable/@Immutable classes across a codebase without verifying they feed a lazy layout with a large dataset.
• When to Add @Stable / @Immutable Under Strong Skipping Mode : Flat data classes with val primitive/String properties in Compose modules are already inferred as stable by the compiler and use .equals() automatically---do not add redundant @Immutable annotations to them. Only add @Stable or @Immutable when the compiler cannot infer stability (e.g. classes from non-Compose modules or interfaces) and a data source (such as Room or MVI reducers) allocates new object instances for unchanged items on every emission, provided the class is small, flat, has no collections (List, Set, Map), and its .equals() check is trivial O(1).
• Make Composables Cheaper Instead of Forcing Skipping: Do not overindex on recomposition counts. Skipping one composable during an active recomposition pass saves little time once composition is scheduled (leaving the house is the bulk of the cost). Focus on making composables cheap to execute, deferring state reads to Layout/Draw, and verifying with benchmarks rather than assuming skipping improves performance.

2. Layouts and measurement optimization (references/layouts.md)

MANDATORY : Before flagging or fixing any issue in this category, you MUST read references/layouts.md.

• Coordinates & Placement : Avoid onGloballyPositioned; use Modifier.onVisibilityChanged for viewport tracking, Modifier.onPlaced or Modifier.onLayoutRectChanged for local bounds, and query requireLayoutCoordinates() on demand inside Modifier.Node event handlers.
• Anchor Floating Content via Custom Layout : When attaching floating labels or tooltips to a component, use a custom Layout measuring and placing both children relative to each other. Never track onGloballyPositioned coordinates in MutableState to position floating content with offset, which causes a 1-frame lag and schedules a second composition pass.
• Phase Deferral for Offsets : Wrap dynamic offsets in lambdas (Modifier.offset { IntOffset(...) }) to skip Composition straight to Layout.
• Tree Depth & Decorative Wrappers : Avoid redundant wrapper Boxes and decorative Canvas nodes; attach modifiers directly or use Modifier.drawBehind.
• Subcomposition Overhead : Avoid BoxWithConstraints / SubcomposeLayout inside hot paths and lazy items; prefer standard modifiers, Modifier.layout, or LayoutModifierNode.
• Intrinsic Measurements: Use intrinsic measurements judiciously and avoid deeply nested intrinsic chains.

3. Lazy layouts optimization (references/lazy-layouts.md)

MANDATORY : Before flagging or fixing any issue in this category, you MUST read references/lazy-layouts.md.

• Lazy Layout Scope Guard : Directives for key and contentType apply strictly to Lazy containers (LazyColumn, LazyRow, LazyGrid). Never flag standard non-lazy containers (Column, Row, Box) iterating over collections.
• Mandatory contentType and Primitive key : Always specify both primitive keys (Int, Long, String) and contentTypes for all items in lazy layouts (LazyColumn, LazyRow, LazyGrid). When using items or itemsIndexed, never omit contentType: contentType = { _, item -> item.type }. Omitting contentType prevents Compose from reusing composition slots during scrolling.
• In-Item Index Lookups : Replace list.indexOf(item) with itemsIndexed to eliminate O(N²) lookups during layout passes.
• **Observable Selection &