Layouts and Modifiers in Depth

Almost every Compose problem that makes beginners say "why does it look like that?" is a layout problem: a button stretches to the full width, padding appears on the wrong side, a background paints outside the border, text is cut off on a small phone. The cure is to understand how Compose measures and places things, and to learn the handful of building blocks that do 95% of the work.

This lesson covers the layout parts of the Jetpack Compose for Android developers programme: The Compose UI toolkit, Implement a real-world design, Fundamentals of Compose layouts and modifiers and Constraints and modifier order (Pathways 1 and 2, https://developer.android.com/courses/pathways/jetpack-compose-for-android-developers-1). You will practise on a recipe screen of your own design.

By the end you will be able to:

• Use Row, Column and Box with Arrangement and Alignment.
• Share space with weight, fillMaxWidth and fractions.
• Predict the effect of modifier order.
• Explain how constraints flow down and sizes flow up.
• Use Scaffold, Surface, Card and Spacer properly.
• Use ConstraintLayout in Compose when nesting gets awkward.
• Use Modifier.layout and intrinsic sizes in simple cases.
• Turn a visual design into composables, and handle small screens, large fonts and right-to-left languages.

Big idea: a parent tells each child "you may be between this small and this big"; the child picks a size inside that range; then the parent decides where to put it.

• The three phases and Compose basics (lesson 37). Layout is phase two.
• Row, Column, Modifier first steps (lesson 16).
• dp and sp units (lesson 16). dp for sizes and spacing, sp for text.
• Preview (lesson 15). Use previews with widthDp, fontScale and locale options throughout.

Constraints down, sizes up

        parent
          |  constraints: minWidth..maxWidth, minHeight..maxHeight
          v
        child  --- measures itself (and its own children) ---+
          |                                                  |
          +---------------- reports a size (w x h) <---------+
        parent places the child at (x, y)

A Constraints object holds a minimum and maximum width and height, in pixels. A child must pick a size within them. This has surprising, useful consequences:

• A composable cannot be bigger than its parent allows, unless the parent allows it.
• Modifier.size(300.dp) inside a parent that is only 200 dp wide yields 200 dp, because the constraint wins (you can override with requiredSize, which you rarely should).
• Each child is measured once, which is why deep nesting is cheap in Compose compared with old Views.

Modifier order matters

A Modifier is an ordered chain. Each element wraps what comes after it, like layers of an onion or nested boxes, from the outside in. So the same elements in a different order give a different result.

// A: background covers padding area
Text("Hello", Modifier.background(Color.Yellow).padding(16.dp))
// B: padding is OUTSIDE the background
Text("Hello", Modifier.padding(16.dp).background(Color.Yellow))

A: background then padding            B: padding then background
+---------------------+               (transparent margin)
|  yellow all over    |                  +-------+
|     Hello           |                  |yellow |
+---------------------+                  | Hello |
(padding is INSIDE yellow)               +-------+

In A the yellow fills the text and the padding. In B the padding is empty space outside the yellow box. The same applies to clickable: Modifier.padding(16.dp).clickable { } makes only the inner area clickable; Modifier.clickable { }.padding(16.dp) makes the padding clickable too, which is usually what you want for a comfortable touch target.

A useful rule for sizing:

Box(Modifier.size(100.dp).padding(8.dp).background(Color.Red)) // red box is 84 dp: padding eats from the 100
Box(Modifier.padding(8.dp).size(100.dp).background(Color.Red)) // red box is 100 dp, with 8 dp margin outside

Read left to right: size first means "I am 100 dp, including whatever follows"; padding first means "leave 8 dp around me, then I am 100".

A common order for a clickable card: size or fillMaxWidth first, then clip, background, clickable, then padding for inner spacing. Experiment with each to see why.

Column and Row

Column stacks children vertically; Row stacks horizontally. Each has two axes: the main axis (the direction of stacking) and the cross axis. You control each with a different parameter.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
Row(
 modifier = Modifier.fillMaxWidth(),
 horizontalArrangement = Arrangement.SpaceBetween, // main axis: distribute
 verticalAlignment = Alignment.CenterVertically // cross axis: align
) {
 Text("Left")
 Text("Middle")
 Text("Right")
}

Arrangements, for a row with extra space (✱ = child):

Arrangement.Start          ✱✱✱.............
Arrangement.Center         ......✱✱✱.......
Arrangement.End            .............✱✱✱
Arrangement.SpaceBetween   ✱......✱......✱
Arrangement.SpaceAround    .✱....✱....✱.   (half-gaps at the ends)
Arrangement.SpaceEvenly    ..✱...✱...✱..   (equal gaps everywhere)
Arrangement.spacedBy(8.dp) ✱ ✱ ✱ ......... (fixed gap, packed at start)

Important: a Row or Column wraps its content by default. Arrangement and Alignment have no visible effect unless the container is bigger than its content: give it fillMaxWidth(), fillMaxSize() or a size. Forgetting this is the most common "why does Arrangement.Center not work?" bug.

Sharing space with weight

Inside a Row or Column, Modifier.weight(w) divides the remaining space among weighted children in proportion:

Row(Modifier.fillMaxWidth()) {
 Text("Label", Modifier.weight(1f)) // gets 1/3 of the remaining width
 Text("Value", Modifier.weight(2f)) // gets 2/3
}

Unweighted children are measured first at their natural size; the leftover is then split among the weighted ones. A single weight(1f) child between two fixed-size ones makes it fill the middle (a classic "title between two icons" toolbar). fill = false lets a weighted child take at most its share but shrink if it needs less.

fillMaxWidth(0.5f) is the other option: a fraction of the parent's maximum, not of the leftover. Use weight to share among siblings; use fractions for a single element.

Box: stacking

Box places children on top of each other, like layers. contentAlignment positions them all, and Modifier.align(...) positions one child.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.background
import androidx.compose.ui.graphics.Color
Box(Modifier.size(200.dp).background(Color.LightGray)) {
 Text("Center", Modifier.align(Alignment.Center))
 Text("Top end", Modifier.align(Alignment.TopEnd))
 Text("Bottom start", Modifier.align(Alignment.BottomStart))
}

Use Box for badges on avatars, text over images, loading overlays and a floating button over content. Children are drawn in order, so later ones appear on top. Notice TopEnd and Start: these respect layout direction, flipping in right-to-left languages such as Arabic or Hebrew. Prefer Start and End over Left and Right, and use padding(start = ..., end = ...).

Surface and Card

Surface is the basic Material container: it gives a background colour from the theme, a shape, elevation and content colour, and it ensures text on it uses the right "on" colour. Card, ElevatedCard and OutlinedCard are ready-made variants. A rule of thumb: never hand-roll a coloured Box for a panel when Surface or Card exists, because those honour dark theme automatically (lesson 40).

Scaffold

Scaffold implements the standard Material screen skeleton: top bar, bottom bar, floating action button, snackbar host and the main content. It passes you innerPadding so content never hides behind the bars:

import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.Icon
import androidx.compose.material3.Scaffold
import androidx.compose.material3.TopAppBar
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RecipesScreen() {
 Scaffold(
 topBar = { TopAppBar(title = { Text("Recipes") }) },
 floatingActionButton = {
 FloatingActionButton(onClick = { /* add recipe */ }) {
 Icon(Icons.Filled.Add, contentDescription = "Add recipe")
 }
 }
 ) { innerPadding ->
 RecipeList(Modifier.padding(innerPadding))
 }
}

Forgetting to apply innerPadding makes the first list item vanish under the top bar, a bug you will meet often. Since Android 15 enforces edge-to-edge drawing for apps targeting recent API levels, Scaffold and its padding also handle the system bars (status bar and navigation bar), which is another reason to use it (lesson 40 covers system bars).

Spacing

• Spacer(Modifier.height(16.dp)) adds fixed empty space between siblings.
• Arrangement.spacedBy(8.dp) on a Column or Row is cleaner than putting a Spacer between every pair.
• Modifier.padding for space around a composable; contentPadding on lazy lists for space inside the scroll area.

Keep spacing on a scale (4, 8, 12, 16, 24, 32 dp). Consistent numbers make a design look intentional.

Most screens are fine with Row, Column and Box. When you need to align things relative to each other in a way that would take three levels of nesting, ConstraintLayout is cleaner. Add its Compose artifact (check the current version at https://developer.android.com/jetpack/androidx/releases/constraintlayout):

[versions]
constraintlayoutCompose = "<latest stable>"
[libraries]
androidx-constraintlayout-compose = { group = "androidx.constraintlayout", name = "constraintlayout-compose", version.ref = "constraintlayoutCompose" }

dependencies {
 implementation(libs.androidx.constraintlayout.compose)
}

A profile header: avatar on the left, name and role stacked to its right, and a follow button pinned to the end, vertically centred with the avatar.

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.background
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.ui.draw.clip
import androidx.compose.ui.unit.dp
import androidx.constraintlayout.compose.ConstraintLayout
@Composable
fun ProfileHeader(name: String, role: String, modifier: Modifier = Modifier) {
 ConstraintLayout(modifier = modifier.fillMaxWidth().padding(16.dp)) {
 val (avatar, title, subtitle, follow) = createRefs()
 Box(
 Modifier
 .size(56.dp)
 .clip(CircleShape)
 .background(MaterialTheme.colorScheme.primary)
 .constrainAs(avatar) {
 start.linkTo(parent.start)
 top.linkTo(parent.top)
 bottom.linkTo(parent.bottom)
 }
 )
 Text(
 name,
 style = MaterialTheme.typography.titleMedium,
 modifier = Modifier.constrainAs(title) {
 start.linkTo(avatar.end, margin = 12.dp)
 top.linkTo(avatar.top)
 }
 )
 Text(
 role,
 modifier = Modifier.constrainAs(subtitle) {
 start.linkTo(title.start)
 top.linkTo(title.bottom)
 }
 )
 Button(
 onClick = { },
 modifier = Modifier.constrainAs(follow) {
 end.linkTo(parent.end)
 top.linkTo(parent.top)
 bottom.linkTo(parent.bottom)
 }
 ) { Text("Follow") }
 }
}

How to read it:

• createRefs() makes references, one per child; constrainAs(ref) { ... } attaches constraints to a child.
• start.linkTo(parent.start) means "my start edge sticks to the parent's start edge". Linking both top and bottom to the parent centres the item vertically.
• margin = 12.dp is spacing from the target.
• You can also use createGuidelineFromStart(0.3f), createBarrier(...) and createHorizontalChain(...), which have no easy Row/Column equivalent, and Dimension.fillToConstraints to stretch between two anchors.

When to choose it: relative positioning, chains, barriers, guidelines, and responsive designs that rearrange via ConstraintSet. When not to: a simple stack or row (use Column and Row); each tool has a cost, and a Row is easier to read and to review.

Seeing constraints at work

Box(Modifier.size(100.dp).background(Color.Gray)) {
 Box(Modifier.size(300.dp).background(Color.Red)) // ask for 300 dp
}

The inner box asks for 300 dp, but its parent only allows up to 100 dp, so it is clamped to 100. Then change the inner modifier to requiredSize(300.dp): it now ignores the constraint and overflows (it still places at the top-left of its parent). It is rarely the right fix; usually the real fix is to change the parent.

fillMaxWidth() sets the minimum width equal to the maximum width, forcing the child to fill. wrapContentSize() resets the minimum to zero, letting the child be its natural size inside a larger parent, a useful trick when a parent's minimum constraints stretch a child you wanted small.

Modifier.layout

When no existing modifier does what you need, you can intercept measuring and placing:

import androidx.compose.ui.layout.layout
fun Modifier.firstBaselineToTop(firstBaselineToTop: Dp) = this.layout { measurable, constraints ->
 val placeable = measurable.measure(constraints)
 val firstBaseline = placeable[FirstBaseline]
 val placeableY = firstBaselineToTop.roundToPx() - firstBaseline
 val height = placeable.height + placeableY
 layout(placeable.width, height) {
 placeable.placeRelative(0, placeableY)
 }
}

The three steps are always: measure the child with measurable.measure(constraints), report a size with layout(width, height), and place it with placeRelative. (Imports: androidx.compose.ui.layout.FirstBaseline, androidx.compose.ui.unit.Dp.) For whole custom containers use the Layout composable with a list of children. This is an advanced tool; use it rarely, and prefer composing existing pieces.

Intrinsic measurements

Children are measured once, so a child cannot normally ask its siblings how big they will be. Intrinsics are a controlled exception: Modifier.height(IntrinsicSize.Min) on a Row makes it as tall as its tallest child's minimum intrinsic height, which lets you draw a divider that matches the text height:

import androidx.compose.foundation.layout.IntrinsicSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.width
import androidx.compose.material3.VerticalDivider
Row(Modifier.height(IntrinsicSize.Min)) {
 Text("Left text", Modifier.weight(1f).padding(8.dp))
 VerticalDivider(Modifier.fillMaxHeight())
 Text("Right text\nwith two lines", Modifier.weight(1f).padding(8.dp))
}

Without IntrinsicSize.Min, the divider's fillMaxHeight would stretch to the whole parent. With it, the row is only as tall as its tallest text. It costs an extra measuring pass, so use it for small, local layouts, not in the middle of long lists.

The programme's Implement a real-world design item gives you a mockup and asks you to rebuild it. The skill is breaking a picture into a tree of containers. Take this recipe card design:

+------------------------------------------+
| [photo, full width, 180 dp tall]         |
|                                          |
+------------------------------------------+
| Jollof Rice with Chicken          [heart]|
| 45 min  ·  4 servings  ·  Easy           |
|                                          |
| A smoky party-style classic that...      |
|                                          |
| [ View recipe ]            [ Share ]     |
+------------------------------------------+

Process:

1. Outer shape: a Card containing a Column.
2. Row 1: a Box or image 180 dp tall, fillMaxWidth, ContentScale.Crop.
3. Row 2: a Row with the title taking weight(1f) and an IconButton at the end.
4. Row 3: a Row of three Texts separated by dots, or a single formatted Text.
5. Body: a Text with a max of 3 lines and an ellipsis.
6. Actions: a Row with Arrangement.SpaceBetween.
7. Spacing: use 16 dp content padding and 8 dp between rows, via padding and spacedBy.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.FavoriteBorder
import androidx.compose.material3.Card
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.ui.text.style.TextOverflow
@Composable
fun RecipeCard(
 title: String,
 meta: String,
 summary: String,
 isFavourite: Boolean,
 onToggleFavourite: () -> Unit,
 onViewClick: () -> Unit,
 onShareClick: () -> Unit,
 modifier: Modifier = Modifier
) {
 Card(modifier = modifier.fillMaxWidth()) {
 Column {
 Box(
 Modifier
 .fillMaxWidth()
 .height(180.dp)
 .background(MaterialTheme.colorScheme.secondaryContainer) // stand-in for the photo
 )
 Column(
 modifier = Modifier.padding(16.dp),
 verticalArrangement = Arrangement.spacedBy(8.dp)
 ) {
 Row(verticalAlignment = Alignment.CenterVertically) {
 Text(
 title,
 style = MaterialTheme.typography.titleLarge,
 modifier = Modifier.weight(1f)
 )
 IconButton(onClick = onToggleFavourite) {
 Icon(
 imageVector = if (isFavourite) Icons.Filled.Favorite else Icons.Filled.FavoriteBorder,
 contentDescription = if (isFavourite) "Remove from favourites" else "Add to favourites"
 )
 }
 }
 Text(meta, style = MaterialTheme.typography.labelLarge)
 Text(summary, maxLines = 3, overflow = TextOverflow.Ellipsis)
 Row(
 modifier = Modifier.fillMaxWidth(),
 horizontalArrangement = Arrangement.SpaceBetween
 ) {
 Button(onClick = onViewClick) { Text("View recipe") }
 OutlinedButton(onClick = onShareClick) { Text("Share") }
 }
 }
 }
 }
}
@Preview(showBackground = true, widthDp = 360)
@Composable
fun RecipeCardPreview() {
 MaterialTheme {
 RecipeCard(
 title = "Jollof Rice with Chicken",
 meta = "45 min  ·  4 servings  ·  Easy",
 summary = "A smoky party-style classic with a rich tomato and pepper base, slow-cooked until the rice is tender and a little crisp at the bottom.",
 isFavourite = true,
 onToggleFavourite = {}, onViewClick = {}, onShareClick = {}
 )
 }
}

Test the design under stress

A design is not finished until it survives real conditions. Add previews for:

@Preview(name = "Small phone", widthDp = 320, showBackground = true)
@Preview(name = "Large font", fontScale = 1.8f, widthDp = 360, showBackground = true)
@Preview(name = "Dark", uiMode = android.content.res.Configuration.UI_MODE_NIGHT_YES, showBackground = true)
@Preview(name = "Arabic RTL", locale = "ar", widthDp = 360, showBackground = true)
@Composable
fun RecipeCardVariants() { /* same body as above */ }

Check each: Does the title wrap instead of clipping at font scale 1.8? Do the two buttons still fit at 320 dp? Does the heart appear on the correct side in right-to-left? Does text remain readable in dark mode? On a very small screen, two Buttons side by side may not fit; the fix might be FlowRow (which wraps children onto a new line) or stacking them vertically below a width breakpoint (lesson 27).

Mistake #1: Arrangement or Alignment has no effect. Why: the container is exactly as big as its content. The fix: give it fillMaxWidth(), fillMaxSize() or a size.

Mistake #2: Wrong modifier order. Symptoms: padding in the wrong place, a tiny clickable area, a background spilling over a clip. The fix: read the chain from the outside in, and reorder.

Mistake #3: fillMaxHeight inside a scrolling Column. What happens: a crash about infinite maximum height. The fix: give the child a fixed height, or use weight only in non-scrolling parents.

Mistake #4: Ignoring innerPadding in Scaffold. What happens: content hides under bars. The fix: apply Modifier.padding(innerPadding).

Mistake #5: Left and right instead of start and end. What happens: broken right-to-left layouts. The fix: use start/end everywhere.

Mistake #6: Hard-coded sizes that ignore font scale. What happens: clipped text for users who set a large font. The fix: let text height wrap; use sp for text, and heightIn(min = ...) instead of a fixed height.

Mistake #7: Nesting many Row/Column to fake ConstraintLayout. What happens: unreadable code. The fix: switch to ConstraintLayout when relationships are irregular.

Mistake #8: Using weight outside a Row or Column scope. Symptom: Unresolved reference: weight. The fix: weight exists only inside RowScope and ColumnScope; pass the modifier in from the caller.

Mistake #9: Tiny touch targets. What happens: users struggle to tap. The fix: keep interactive elements at least 48 dp square; Material components do this for you, custom clickable boxes do not.

Mistake #10: Using requiredSize to force a size. What happens: overflow and clipping. The fix: fix the parent's constraints instead.

Question 1. How do constraints and sizes flow through the layout tree?

Question 2. Why do Modifier.padding(16.dp).background(c) and Modifier.background(c).padding(16.dp) look different?

Question 3. What is the difference between Arrangement and Alignment in a Row?

Question 4. When would you choose ConstraintLayout over nested Row and Column?

Question 5. Why use Scaffold's innerPadding?

Go deeper: official resources

• Jetpack Compose for Android developers, Pathway 1: Compose essentials
• Pathway 2: Layouts, theming and animation
• Jetpack Compose layouts codelab
• Jetpack Compose course page