Avoiding Subcomposition Pitfalls

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/recomposition/avoiding-subcomposition-pitfallsThe 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 when a Compose tree uses SubcomposeLayout, BoxWithConstraints, or Scaffold and the developer reports extra measure passes, slow first frame, or layout passes running content composition repeatedly. Covers…

---
name: avoiding-subcomposition-pitfalls
description: Use this skill when a Compose tree uses SubcomposeLayout, BoxWithConstraints, or Scaffold and the developer reports extra measure passes, slow first frame, or layout passes running content composition repeatedly. Covers why SubcomposeLayout composes its slots during the measure phase, why BoxWithConstraints forces a subcomposition for every new Constraints value, why nesting Scaffold or BoxWithConstraints multiplies the cost, when a custom Layout or Modifier.layout { } replaces SubcomposeLayout, and how to use SubcomposeLayoutState's slot reuse policy and precompose APIs when SubcomposeLayout is genuinely required. Use when the developer mentions BoxWithConstraints, SubcomposeLayout, Scaffold, "extra measure pass", "double measurement", "first frame slow", "subcompose", or notices that wrapping content in BoxWithConstraints regresses scroll perf inside a LazyColumn.
license: Apache-2.0. See LICENSE for complete terms.
metadata:
  author: Jaewoong Eum (skydoves)
  keywords:
  - jetpack-compose
  - performance
  - subcomposelayout
  - boxwithconstraints
  - scaffold
  - layout-phase
  - measure-pass
  - subcomposition
---

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

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 Avoiding Subcomposition Pitfalls

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

Spotted something wrong? Report a correction · Methodology