Avoiding Subcomposition Pitfalls

Avoiding Subcomposition Pitfalls — Keep Composition Out of the Measure Pass

SubcomposeLayout runs its content's composition during the measure pass, not during the parent's composition pass. That trades extra layout cost for the ability to use measured constraints inside the children's composition. BoxWithConstraints, material3.Scaffold, and the lazy layouts are all built on top of it, so the cost is invisible until it nests or lands inside a hot path. This skill teaches Claude how to detect the misuse, how to replace SubcomposeLayout with a cheaper primitive when its power is not needed, and how to keep it efficient when it is.

When to use this skill

• The developer wraps content in BoxWithConstraints purely to read maxWidth / maxHeight and pick between a few composables, and the screen feels heavy at first frame or on configuration change (rotation, IME show).
• A BoxWithConstraints or Scaffold is nested inside another BoxWithConstraints or Scaffold, multiplying subcomposition cost.
• A BoxWithConstraints sits inside a LazyColumn/LazyRow item and the developer reports scroll jank that did not exist before the wrap was added.
• The developer manually authors a SubcomposeLayout block but only uses constraints to compute final positions, never to drive child composition.
• The Layout Inspector or a Perfetto trace shows Compose:applyChanges or measure-phase composition counts that scale with parent constraint changes (rotation, drag-to-resize, animated container size).
• A custom SubcomposeLayout's measurePolicy block allocates a fresh composable lambda inside subcompose(slotId) { … } on every measurement. AndroidX maintains an internal lint check named ComposableLambdaInMeasurePolicy (in compose/lint/internal-lint-checks/) that flags exactly this pattern on its own codebase; published APIs like BoxWithConstraints, material.Scaffold, and material3.TabRow suppress that check because the trade-off is fundamental to their public contract. App-side code that reproduces the pattern pays the same cost without the suppression rationale.

When NOT to use this skill

• The developer needs to compose a child whose content depends on another child's measured size — that is the canonical SubcomposeLayout use case and there is no cheaper primitive. Keep SubcomposeLayout; tune it (see Pattern: Tuning a justified SubcomposeLayout).
• The slow path is inside a LazyColumn item but the cause is unstable parameters, not subcomposition. Diagnose with ../../stability/diagnosing-compose-stability/SKILL.md first.
• The state read driving repeated measurement is an animation value rather than a structural constraint. That is ../deferring-state-reads/SKILL.md.
• The user wants to optimize lazy list prefetch — that is ../../lists/configuring-lazy-prefetch/SKILL.md.

Prerequisites

• Familiarity with Compose's three phases (Composition, Layout, Draw). If unsure, read ../deferring-state-reads/references/three-phases.md first.
• A release build with R8 for any final measurement. ../../measurement/testing-compose-in-release-mode/SKILL.md covers why debug builds lie.
• Layout Inspector or Perfetto trace tooling. ../../measurement/tracing-recompositions-at-runtime/SKILL.md covers wiring androidx.compose.runtime:runtime-tracing so that measure-phase work shows up in system traces.
• A modern Compose UI version that exposes the SubcomposeSlotReusePolicy(maxSlotsToRetainForReuse: Int) factory and pausable subcomposition on the lazy-list path. Both ship in the current androidx.compose.ui:ui / androidx.compose.foundation:foundation artifacts; check the release notes at https://developer.android.com/jetpack/androidx/releases/compose-ui and https://developer.android.com/jetpack/androidx/releases/compose-foundation if pinning to an older release.

Workflow

• 1. Identify every SubcomposeLayout user in the hot path. Grep the affected screen for BoxWithConstraints, Scaffold, SubcomposeLayout, and any custom @Composable that delegates to one. The material3.Scaffold and foundation.layout.BoxWithConstraints are both implemented with SubcomposeLayout; their cost is identical.

• 2. For each user, decide whether the constraints are actually consumed during composition. A BoxWithConstraints that reads maxWidth only to pass it to a child as a parameter is wasting the subcomposition machinery. A BoxWithConstraints that picks between two completely different @Composable trees based on maxWidth < 600.dp is using it correctly.

• 3. Replace unjustified BoxWithConstraints with a cheaper primitive. If the consumer only needs the final size in pixels (e.g. to compute an offset, an alpha, a draw command), use Modifier.layout { measurable, constraints -> … } or Modifier.onSizeChanged { … } instead. Both run during the layout phase without spinning up a new composition.

• 4. Avoid nesting subcomposing layouts. Two Scaffolds nested, or a BoxWithConstraints inside a Scaffold slot that itself contains another BoxWithConstraints, multiplies measure-phase composition. Hoist the outer one to the screen root and use ordinary Box / Column / Row for the inner branches.

• 5. Never wrap a LazyColumn/LazyRow item in BoxWithConstraints. Each item subcomposes during measurement. If the item needs the available width, pass it down once from the parent (the LazyColumn already knows its constraints) or use Modifier.fillMaxWidth().onSizeChanged { … } for one-time sizing.

• 6. When SubcomposeLayout is justified, configure SubcomposeLayoutState(SubcomposeSlotReusePolicy(n)). The state object retains up to n previously-used slots so the next subcomposition reuses their slot table and node subtree instead of paying for a fresh composition. The factory SubcomposeSlotReusePolicy(maxSlotsToRetainForReuse: Int) ships in androidx.compose.ui.layout.

• 7. For predictable upcoming slots, call state.precompose(slotId, content) on a previous frame. It returns a PrecomposedSlotHandle; the next subcompose(slotId, …) during measurement skips the composition step. This is exactly how the lazy layouts spread item composition across frames.

• 8. Verify in a Perfetto system trace. Add androidx.compose.runtime:runtime-tracing and confirm that Compose:recompose and Compose:applyChanges no longer fire during scroll or resize ticks at the rate of the parent's constraint changes. The measured screen should show subcomposition only on actual structural change (e.g. rotation), not on every frame.

Patterns

Pattern: BoxWithConstraints used to read size — replace with Modifier.onSizeChanged

// WRONG
@Composable
fun ParallaxHeader(scrollOffset: () -> Float) {
    BoxWithConstraints {
        val widthPx = with(LocalDensity.current) { maxWidth.toPx() }
        Image(
            painter = painterResource(R.drawable.hero),
            modifier = Modifier
                .fillMaxWidth()
                .height(220.dp)
                .graphicsLayer {
                    translationX = scrollOffset() * widthPx * 0.2f
                },
            contentDescription = null,
        )
    }
}
// WRONG because: BoxWithConstraints subcomposes its content during the measure phase. Each
// new constraint (rotation, IME show, animated parent size) re-runs that subcomposition just
// to read maxWidth, when a Modifier.onSizeChanged would have given the same value with no
// extra composition.

// RIGHT
@Composable
fun ParallaxHeader(scrollOffset: () -> Float) {
    var widthPx by remember { mutableStateOf(0f) }
    Image(
        painter = painterResource(R.drawable.hero),
        modifier = Modifier
            .fillMaxWidth()
            .height(220.dp)
            .onSizeChanged { widthPx = it.width.toFloat() }
            .graphicsLayer {
                translationX = scrollOffset() * widthPx * 0.2f
            },
        contentDescription = null,
    )
}

onSizeChanged runs in the layout phase (no subcomposition); the underlying onRemeasured is invoked on every layout pass and forwards to the user callback when the measured size differs from the previous size. The graphicsLayer block runs in Draw with the latest widthPx and the latest scroll offset.

Pattern: BoxWithConstraints to pick a layout — keep it but hoist it

// WRONG
@Composable
fun ProductCard(product: Product) {
    BoxWithConstraints {
        if (maxWidth < 360.dp) {
            CompactProductCard(product)
        } else {
            WideProductCard(product)
        }
    }
}

@Composable
fun ProductGrid(products: List<Product>) {
    LazyVerticalGrid(columns = GridCells.Fixed(2)) {
        items(products) { ProductCard(it) }
    }
}
// WRONG because: every grid cell wraps its content in BoxWithConstraints. Each cell pays
// for a subcomposition during the grid's measure pass. With 200 cells visible across a long
// scroll session, that is 200 redundant subcompositions on every measurement.

// RIGHT
@Composable
fun ProductGrid(products: List<Product>) {
    BoxWithConstraints {
        val isCompact = maxWidth / 2 < 360.dp
        LazyVerticalGrid(columns = GridCells.Fixed(2)) {
            items(products) { product ->
                if (isCompact) CompactProductCard(product) else WideProductCard(product)
            }
        }
    }
}

The single BoxWithConstraints at the grid root subcomposes once per parent constraint change. The decision flows into every item as a plain Boolean, which is stable and skippable.