SubcomposeLayout and BoxWithConstraints Internals in Jetpack Compose
Jetpack Compose normally separates composition from measurement: you declare the interface first, then the framework sizes and positions it. SubcomposeLayout reverses that order for cases where the available space must decide what gets composed. This guide explains its API, its internal node and slot management, how BoxWithConstraints builds on it, and when the extra cost is worthwhile.
Why composition sometimes has to wait for measurement
A standard layout cannot answer a question such as which structure fits the width available, because that width is not known until measurement. Adaptive layouts, lazy lists that show only visible items, and layouts that measure one child before choosing another all hit the same ordering problem. SubcomposeLayout solves it by letting a measure policy request fresh composition, receive measurable children, and then size and place them. The composable signature and the scope interface are given in protected modules code0001 and code0002. The key addition is a subcompose operation: during measurement it composes the supplied content immediately and returns measurables, while a slot identifier tracks identity for recomposition, reuse and state retention.
Three node regions and the subcompose flow
Internally, state is held on the layout node and children are kept in three regions, shown in code0003: active nodes used in the current pass, reusable nodes retained for later, and precomposed nodes prepared before use. Active nodes are looked up by slot identifier. Reusable nodes are kept rather than disposed at once so their composition state can survive. Precomposed nodes are tracked separately until a measure pass claims them. This layout is the basis for avoiding needless disposal and recreation.
How a slot is found, positioned and composed
Calling subcompose during measurement follows a fixed sequence, detailed in code0004. First the internal state is checked and the call is confirmed to be inside a measure or layout pass, including lookahead variants. Next the slot is resolved: an active node wins, then a precomposed node, then a compatible reusable node, and only then a new node is created. The node is moved to the expected position so active children stay at the front in subcomposition order. Composition then runs into that node, and the appropriate measurables are returned for a normal or lookahead pass. A practical checklist is: validate the pass, resolve the slot in that order, fix ordering, compose, and return measurables.
Slot reuse: retain, deactivate, then match again
After measurement, unused slots are either retained or disposed, as shown in code0005. A reuse policy decides which slot identifiers to keep. Retained compositions are deactivated rather than destroyed; code0006 shows that deactivation may flow through a reusable content host or be performed directly, synchronously or out of frame. When a slot is needed again, code0007 first searches for an exact identifier match, then for a compatible reusable slot. A reused node is forced to recompose through the reuse path so existing state can be maximised. Unique keys matter here: reusing a slot identifier for a different item can trigger the ordering precondition described in code0004.
Regular, lookahead and approach passes
The measure policy in code0008 distinguishes a regular pass, a lookahead pass and an approach pass. Disposal is deferred until placement, because placement is when the framework knows which children were actually used. In a lookahead scope, disposal waits until the approach pass has had a chance to take ownership of subcompositions. The approach pass uses its own index and scope and can compose items that lookahead did not. This separation prevents premature disposal while still cleaning up unused slots.
How BoxWithConstraints turns constraints into content
BoxWithConstraints is a compact consumer of this machinery, shown in code0009. Measurement creates a scope that exposes the incoming constraints as density-aware values, as in code0010. It then subcomposes the caller content with that scope as receiver. Because the scope already holds maxWidth, maxHeight and related values, the content can branch immediately, for example choosing a wide or narrow structure as in code0011. After subcomposition, a standard box measure policy handles sizing and alignment. The design therefore needs no separate node tracking or reuse logic of its own.
Where this pattern earns its keep
Lazy lists compose visible items as space and scroll position change and recycle the rest. Tab layouts can measure tabs before composing an indicator from their positions. Scaffold-like layouts can measure bars before composing content into the remaining space. Adaptive material layouts use constraint-aware composition to switch structure by size and orientation. A concrete dynamic-width example is a row of purchase options whose count is configured remotely: code0012 subtracts padding and spacing from maxWidth, divides by the number of options, and gives every option the same width. That pattern generalises to any server-driven or user-configured list whose count is not fixed at build time.
Performance costs and the intrinsic-measurement limit
Subcomposition during measurement is synchronous and does more work than ordinary composition: it sets up or reuses a composition, runs the content, applies state changes, materialises nodes and returns measurables. Slot reuse reduces full recomposition but still needs reactivation and reconciliation, so long measure passes can drop frames. There is also a hard limit: intrinsic measurement is unsupported, because the content to be sized is not known until real constraints arrive. Code0013 gives the exact error guidance, including replacing a parent with a custom layout or adding a size modifier where appropriate. Use SubcomposeLayout when constraint-driven composition is essential, keep subcomposed content lean, give slots stable unique identifiers, and avoid intrinsic queries.
[Active nodes] [Reusable nodes] [Precomposed nodes]