OpenParable
Skip to content
← Back to skills

Compose State Deferred Reads

Development
compose-state-deferred-reads

Compose State Deferred Reads is an Agent Skill for development published in the vitorpamplona/amethyst repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when Jetpack Compose code reads scroll, animation, gesture, or other frame-rate State in composition, passes changing values across composable boundaries, or uses value-form layout/draw modifiers. Technique-layer skill — complements the codebase-specific compose-expert.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vitorpamplona/amethyst/blob/HEAD/.claude/skills/compose-state-deferred-reads/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/compose-state-deferred-reads, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Compose state deferred reads

Core principle

State reads invalidate the phase that reads them. If a State<T> is read in a composable body, changes invalidate composition. If it is read in layout or draw, changes can invalidate only layout or draw. Frame-rate state such as scroll offsets, animations, and drag positions usually belongs in layout/draw, not composition.

The fix is structural: keep the State<T> or a provider lambda, and read the value inside a layout/draw callback.

When to use this skill

  • val x by animate*AsState(...) is passed to Modifier.offset(x = ...), Modifier.size(...), Modifier.graphicsLayer(...), or another value-form modifier.
  • LazyListState.firstVisibleItemScrollOffset, ScrollState.value, Animatable.value, or gesture state is read in a composable body.
  • A composable takes scrollOffset: Int, progress: Float, dragOffset: Offset, or similar frame-rate values.
  • Recomposition counters climb during scroll, animation, or gestures even when data is stable.

1. Prefer block-form modifiers

Several modifiers have value forms and block forms. The value form receives values already read in composition; the block form can read during layout or draw.

// Before: animated value read in composition by the `by` delegate
@Composable
fun SelectionPill(selectedIndex: Int) {
    val offsetX by animateDpAsState(120.dp * selectedIndex)
    Box(Modifier.offset(x = offsetX))
}

// After: State is kept, value is read in the layout-phase offset block
@Composable
fun SelectionPill(selectedIndex: Int) {
    val offsetX = animateDpAsState(120.dp * selectedIndex)
    Box(
        Modifier.offset {
            IntOffset(offsetX.value.roundToPx(), 0)
        },
    )
}

Common replacements:

Composition readDeferred read
Modifier.offset(x = animatedX)Modifier.offset { IntOffset(animatedX.value.roundToPx(), 0) }
Modifier.graphicsLayer(translationY = y)Modifier.graphicsLayer { translationY = yProvider() }
val radius by animateFloatAsState(...); drawBehind { drawCircle(radius = radius) }val radius = animateFloatAsState(...); drawBehind { drawCircle(radius = radius.value) }

The drawBehind block is already draw-phase; the important part is that the State.value read also happens inside that block.

2. Pass providers across composable boundaries

If the fast-changing value would cross a composable boundary, pass a provider lambda instead of a snapshot value:

// Before: HomeScreen reads scroll offset in composition and passes the value down
@Composable
fun HomeScreen() {
    val listState = rememberLazyListState()
    LazyColumn(state = listState) {
        item { HeroImage(scrollOffset = listState.firstVisibleItemScrollOffset) }
    }
}

@Composable
fun HeroImage(scrollOffset: Int, modifier: Modifier = Modifier) {
    AsyncImage(
        model = "...",
        modifier = modifier.graphicsLayer(translationY = -scrollOffset / 2f),
    )
}

// After: the only read happens inside graphicsLayer
@Composable
fun HomeScreen() {
    val listState = rememberLazyListState()
    LazyColumn(state = listState) {
        item {
            HeroImage(
                scrollOffsetProvider = {
                    if (listState.firstVisibleItemIndex == 0) {
                        listState.firstVisibleItemScrollOffset
                    } else {
                        0
                    }
                },
            )
        }
    }
}

@Composable
fun HeroImage(scrollOffsetProvider: () -> Int, modifier: Modifier = Modifier) {
    AsyncImage(
        model = "...",
        modifier = modifier.graphicsLayer {
            translationY = -scrollOffsetProvider() / 2f
        },
    )
}

Suffix provider parameters with Provider when that clarifies the deferred-read contract.

3. Other layout/draw read sites

State reads can also be deferred inside:

  • Modifier.layout { measurable, constraints -> ... }
  • Custom Alignment.align(...)
  • drawWithContent, drawBehind, and other draw modifiers
  • Block-form layer/layout modifiers such as graphicsLayer { ... } and offset { ... }

Use these when the state changes where something is placed or painted. If the state decides which composables exist, it belongs in composition.

Quick reference

SymptomDiagnosisFix
val x by animateFloatAsState(...) then Modifier.offset(...)by reads in compositionKeep State<Float> and read .value in offset {}
Modifier.graphicsLayer(translationY = animatedY)Property-argument form uses composition valuesUse graphicsLayer { translationY = ... }
Child(scrollOffset = listState.firstVisibleItemScrollOffset)Fast-changing value crosses boundaryChild(scrollOffsetProvider = { ... })
Draw block still recomposes every frameValue was read before draw blockMove the State.value read inside the draw block
State chooses between different UI branchesComposition decisionKeep the read in composition

When NOT to apply

  • The state controls which composables are emitted.
  • The animation is one-shot, cheap, and clarity wins.
  • You are writing tests where direct value assertions are simpler.
  • Runtime evidence shows recomposition is not the bottleneck.

Related