Ordering Modifier Chains

Ordering Modifier Chains — Why padding(8.dp).background(Red) ≠ background(Red).padding(8.dp)

Modifier order matters because each modifier wraps the next as a function. Modifier.padding(8.dp).background(Red) shrinks constraints first, so the background paints INSIDE the padded region — the surrounding 8 dp margin has no red. Conversely, Modifier.background(Red).padding(8.dp) paints red across the parent's full bounds before insetting the content. Wrong order is the most common Compose UI bug after missing keys. This skill teaches Claude how to read a chain top-to-bottom and reorder it correctly.

When to use this skill

• The developer asks "why does the click area extend past the visible button?", "why is my ripple bouncing on the wrong shape?", "why is the background painted in the wrong area?", or "does Modifier order matter?".
• A code review shows a chain like Modifier.padding(...).clickable { }, Modifier.background(...).clip(...), or Modifier.alpha(state.value).graphicsLayer { }.
• A button's tap target leaks into the surrounding padding, or the corner radius is not honored on the background.
• A clip on a parent is failing to mask a child draw, or graphicsLayer { alpha = 0.5f } is half-applying to siblings.
• The developer is considering hoisting a Modifier chain via remember { Modifier.… } "for perf".

When NOT to use this skill

• The chain order is correct and the symptom is elsewhere (state read in the wrong phase, missing keys in a lazy layout). Diagnose with ../../recomposition/deferring-state-reads/SKILL.md or ../../lists/optimizing-lazy-layouts/SKILL.md first.
• The custom modifier itself is the problem (composed { } legacy, missing diff) → see ../migrating-to-modifier-node/SKILL.md.
• The question is whether to make a custom modifier — this skill assumes you already have a chain of built-ins and need to order them right.

Prerequisites

• Basic familiarity with Modifier composition vocabulary (padding, background, clip, clickable, graphicsLayer).
• Compose UI any supported version — modifier ordering semantics have been stable since 1.0.
• A real-device, release build for any final perf claim about hoisting (skydoves hot take #5: debug builds lie).

Workflow

• 1. Identify the symptom precisely. Match it to one of: paint region wrong, click / pointer area wrong, ripple bounds wrong, clip area wrong, padding measurement wrong, graphicsLayer scope wrong. Each maps to a specific reorder.

• 2. Read the chain top-to-bottom — each modifier's effect applies to everything BELOW it. Treat the chain as nested function calls: Modifier.a().b().c() means "a wraps (b wraps (c))". The top modifier is the outermost wrapper; the bottom modifier is closest to the content.

• 3. Apply the canonical reorder for the symptom. The patterns below cover the four most common cases (padding vs background, clickable placement, clip before background, graphicsLayer scope).

• 4. Pay special attention to these modifiers — order is observable, not stylistic:

  • clickable — the pointer hit area is the bounds AT ITS POSITION in the chain. Anything ABOVE it (outer) is included; anything BELOW it (inner) is not.
  • clip — clips everything BELOW it (inner). Anything ABOVE it is unclipped.
  • background — paints across the bounds AT ITS POSITION in the chain.
  • padding — subtracts from the available space passed to everything BELOW it.
  • graphicsLayer — wraps everything BELOW it in a render layer (alpha, transforms, clipping all apply to the subtree under it).

• 5. Decide on touch-target accessibility. Material's 48dp minimum touch target is achieved by placing clickable ABOVE the visual padding so the padded area is tappable. The trade-off: ripples will also fire in the padding. For visual-area-only clicks, clickable goes BELOW padding.

• 6. Resist hoisting a Modifier chain via remember "for perf". Compose already interns structurally-equal Modifier chains internally; remember { Modifier.fillMaxWidth().padding(16.dp) } is a micro-optimization that rarely shows up in a profile. MUST NOT add such a remember without first proving with a FrameTimingMetric benchmark that the unhoisted chain measurably regresses. See ../../lists/optimizing-lazy-layouts/SKILL.md for the broader allocation-in-items lambda discussion.

Patterns

Pattern: background OUTSIDE vs INSIDE padding

// WRONG (when the intent is "padded box with red fill")
Box(Modifier.padding(8.dp).background(Color.Red))
// WRONG because: padding is applied first; background then paints across the inner (padded) bounds — the result is a smaller red region, with no red in the padded margin. If the design intent was "red card with 8dp internal padding", red is on the wrong side of the padding.

// RIGHT — red fills the box; content is inset by 8dp.
Box(Modifier.background(Color.Red).padding(8.dp)) { /* content */ }

The reverse is also a valid composition — but only when the developer specifically wants the red to NOT extend into the surrounding padding (e.g. a small inner badge). Default to background → padding for "card with internal padding".

Pattern: clickable ABOVE vs BELOW padding (touch target vs visual area)

// WRONG (when the click should fire only on the visible icon)
Box(Modifier.padding(16.dp).clickable { onTap() })
// WRONG because: clickable's hit region is its position in the chain — and at this position, the bounds INCLUDE the padding. Taps in the padding fire onTap and ripple bounces past the visible icon.

// RIGHT — click only fires on the visible content area.
Box(Modifier.clickable { onTap() }.padding(16.dp))

// RIGHT — accessibility 48dp touch target: extend the tap area into the padding intentionally.
Box(
    Modifier
        .padding(8.dp)            // outer spacing
        .clickable { onTap() }    // tap fires across the next size step
        .padding(16.dp)           // visual padding inside the tap area
)

The 48dp minimum touch target (Material) is achieved by deliberately placing clickable so that it sits OUTSIDE the visual padding but INSIDE any external spacing. Pick whichever matches the design intent — neither order is "more correct"; they describe different products.

Pattern: clip BEFORE vs AFTER background

// WRONG (rounded card with red fill)
Box(Modifier.background(Color.Red).clip(RoundedCornerShape(8.dp)))
// WRONG because: background paints first across square bounds; clip then applies to children only. The red rectangle is unclipped — corners stay square.

// RIGHT — clip wraps the background, so the red is rounded.
Box(Modifier.clip(RoundedCornerShape(8.dp)).background(Color.Red))

For modifiers that combine clip + background semantics, Modifier.background(color = ..., shape = ...) does both in one node and avoids the ordering question:

// RIGHT — single modifier handles shape clipping and fill atomically.
Box(Modifier.background(Color.Red, RoundedCornerShape(8.dp)))

Pattern: graphicsLayer wraps everything BELOW it

// RIGHT — alpha applies to the entire subtree (background + content).
Box(
    Modifier
        .graphicsLayer { alpha = 0.5f }
        .background(Color.Red)
        .padding(8.dp)
) { Text("Half-faded card") }

// WRONG — alpha only fades the content; background is fully opaque.
Box(
    Modifier
        .background(Color.Red)
        .padding(8.dp)
        .graphicsLayer { alpha = 0.5f }
) { Text("Surprising opacity") }
// WRONG because: graphicsLayer wraps only what's below it; the background painted above is not in its layer.

This is the most common "why is my fade weird" bug after wrong-phase animation reads. Place graphicsLayer at (or near) the top of the chain when the intent is "fade this entire visual unit".

Pattern: clickable inside graphicsLayer (the hit-test surprise)

// RIGHT — graphicsLayer { } wraps clickable; ripple is captured into the layer.
Box(
    Modifier
        .graphicsLayer { alpha = 0.9f }
        .clickable { onTap() }
        .padding(16.dp)
)

graphicsLayer does NOT change hit-test geometry — clickable hit-tests against its own position in the chain, regardless of whether a graphicsLayer is wrapping it. If the graphicsLayer applies a transform (translation, scale, rotation), the hit test follows the laid-out (pre-transform) bounds; Modifier.pointerInput { } with explicit hit testing is required for transformed hit-tests. Cross-reference ../../recomposition/deferring-state-reads/SKILL.md for the wider phase discussion.