← All articles

The Compose Measure Phase: Measurable, Constraints, Placeable, layout(), place()

One-line definition: The measure phase is a top-down conversation where the parent hands a child a budget (Constraints), the child returns a sized result (Placeable), and the middleman in between can rewrite both — passing different constraints down and reporting a different size up.

1. Why this matters (the problem it solves)

Every custom layout modifier (Modifier.layout { }, LayoutModifierNode) and every custom Layout composable lives inside the measure phase. Understanding it correctly is the difference between writing a 5-line modifier that works and getting hopelessly confused about why constraints “won’t let” you do something.

The most common confusion: thinking the parent’s constraints bind what you can give to your child. They don’t. The parent’s constraints bind only the size YOU report. What you hand to your child is entirely your choice. This is the mental shift that unlocks bleed modifiers, scrollable content larger than the viewport, custom min-size enforcers, etc.

2. The four roles in Modifier.layout { measurable, constraints -> ... }

fun Modifier.bleedHorizontal(padding: Dp): Modifier = layout { measurable, constraints ->
    val extraPx = padding.roundToPx() * 2
    val placeable = measurable.measure(constraints.offset(horizontal = extraPx))
    layout(placeable.width - extraPx, placeable.height) {
        placeable.place(-padding.roundToPx(), 0)
    }
}

measurable — the unmeasured child

A Measurable is the child before it has decided its size. The only thing you can do with it is call .measure(someConstraints), which runs measurement and returns a Placeable. Until you call .measure(), the child has no width or height yet.

Mental model: a recipe with no oven temperature yet.

constraints (the parameter) — the budget your parent gave YOU

A Constraints is a range: min..max for width and height. It says “you must report a size within this range”.

Critically: this binds only what you report back via layout(...). It does NOT bind what you give to your child. You are a middleman; you choose what budget to hand down, separately from what budget you received.

Mental model: rules for your own final size.

placeable — the measured child, ready to be placed

When you call measurable.measure(someConstraints), the child sizes itself within the constraints you gave it (not the parent’s original constraints) and returns a Placeable. Its .width and .height are now fixed — already chosen, baked in. Only its (x, y) position is up to you.

Mental model: a sized rectangle waiting for an (x, y) placement.

layout(width, height) { ... } — what YOU report to your parent + where you place children

The width and height you pass here is your reported size; it must satisfy the parent’s constraints. Inside the lambda, you call placeable.place(x, y) for each child to position them in your coordinate space.

Mental model: handing a rectangle back upstream + filling it (or overfilling it) with your placeables.

3. The four sizes that exist (keeping them straight is the whole game)

For the bleed example, with a 332dp-wide LazyColumn applying 16dp horizontal padding, four distinct widths flow through the function:

Width Where it comes from Value Meaning
constraints.maxWidth Parent → us 300 What the parent allows US to be
(constraints.offset(...)).maxWidth Us → child 332 What we let the CHILD be
placeable.width Child → us 332 What the child actually became
layout(width, ...) arg Us → parent 300 What we REPORT to the parent

The bleed lives in the gap between row 3 (332) and row 4 (300). The child paints 332 wide; we admit only 300. The 32dp difference spills out — half on each side, controlled by place(-16, 0).

4. Visual flow

┌──────────────┐
│   PARENT     │  hands DOWN: constraints (max=300)
│ (LazyColumn) │
└───────┬──────┘
        │  Constraints(min=300, max=300)
        ▼
   ┌────────────────────────────────────────────────────┐
   │  bleedHorizontal { measurable, constraints -> ...  │
   │                                                    │
   │  STEP A — receive constraints (max=300)            │
   │                                                    │
   │  STEP B — build NEW constraints (max=332)          │
   │           constraints.offset(horizontal = 32)      │
   │                                                    │
   │  STEP C — measurable.measure(newConstraints)       │
   │           ↓ child measures itself at 332           │
   │           ↓ returns a Placeable of width 332       │
   │                                                    │
   │  STEP D — layout(placeable.width - 32, ...)        │
   │           = layout(300, height)                    │
   │           ↓ tells PARENT we are 300                │
   │                                                    │
   │  STEP E — placeable.place(-16, 0)                  │
   │           ↓ paints child shifted left              │
   └────────────────────────────────────────────────────┘
        │
        │  reported up: width=300 (parent is happy)
        ▼
┌──────────────┐
│   PARENT     │  thinks the slot was 300; actual paint is 332
└──────────────┘

The resulting paint vs reported slot:

                       0   16              316   332
parent's view:         │   │                │     │
   reported slot       │   ╞════ 300 ═══════╡     │   ← what LazyColumn knows
                       
   actual paint        ╞═════════ 332 ═════════╡      ← what the user sees
                       ▲                       ▲
                    placed at x=-16          ends at x=316
                    (left bleed)             (right bleed, from width)

5. Why specifically placeable.width - extraPx and not just 300?

Both work for HorizontalDivider (which uses fillMaxWidth). But placeable.width - extraPx is the correct general expression.

The expression reads: “however wide the child became, subtract the extra room we gave it.”

In every case, this reports the size the child would have been if we hadn’t lied.

placeable.width - extraPx is the inverse of constraints.offset(horizontal = extraPx). We added going down; we subtract coming back up. The parent never sees that we expanded.

Hard-coding 300 would report 300 even for a 40dp text. The LazyColumn would reserve a 300dp slot for what’s really an 8dp item. Wrong for general-purpose use.

6. Full code with annotations

fun Modifier.bleedHorizontal(padding: Dp): Modifier = layout { measurable, constraints ->
    val extraPx = padding.roundToPx() * 2

    // Hand the CHILD a wider budget than our parent gave us.
    // Constraints.offset(horizontal = px) adds to BOTH min and max,
    // so a fillMaxWidth() child picks up the new (wider) size.
    val placeable = measurable.measure(
        constraints.offset(horizontal = extraPx)
    )

    // Report OUR OWN size to the parent. Subtract the extra we added
    // so the parent sees the size the child WOULD have been.
    // The parent's constraints bind THIS line, not the measure() call above.
    layout(placeable.width - extraPx, placeable.height) {
        // Place the child shifted left by `padding`. Its measured width
        // (which is `placeable.width`, larger than what we report)
        // carries the right edge `padding` past our reported right edge.
        placeable.place(-padding.roundToPx(), 0)
    }
}

7. Key APIs

8. Common mistakes

  1. Believing parent’s constraints limit what you can give the child. They don’t. They limit only what you layout(width, height, ...) back.
  2. Hard-coding the reported size (layout(300, ...)) instead of computing it from placeable.width. Works for one specific child, breaks for any other.
  3. Calling measurable.measure() more than once. It’s a one-shot call. Multiple calls are an error in Modifier.layout / LayoutModifierNode. (Multiple measures are only legal in SubcomposeLayout — separate concept.)
  4. Reporting a size outside the parent’s constraints without clamping. The layout system will clamp anyway, but you’ll get unexpected results. Use constraints.constrainWidth(...) defensively.
  5. Forgetting that place() takes one (x, y) and expecting symmetric bleed by giving two coordinates. The width carries the right edge automatically — see compose-custom-modifiers.md for the math.

9. Best practices

10. Related concepts / what to learn next

11. Quick recall