Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 104 ยท Jetpack Compose Fundamentals

Row, Column, Box and Arrangements

Learn the three basic Compose layouts, how Arrangement and Alignment place children, how weight shares space, and how constraints flow down and sizes flow up.

Almost every screen is built from three layouts. A Column stacks its children vertically, a Row places them side by side, and a Box puts them on top of each other. Nest them and you can describe most interfaces. What makes them powerful is a small set of rules about how they divide the available space, and that is what this lesson covers: Arrangement, Alignment, weight, Spacer, and the way Compose measures a layout in a single pass.

The real layout code needs Android and Compose, so the Compose snippets are read-only. The runnable TryIt blocks are plain Kotlin stand-ins that implement the same arithmetic (weights and arrangements) and print the result as numbers and a text ruler. They are models of the rules, not Compose itself. You met composables in Composable Functions; modifiers such as fillMaxWidth and padding appear here and get their own lesson in Modifiers.

The three basic layouts

Kotlin
// read-only example: needs Android and Compose
Column {
    Text("Title")
    Text("Subtitle")
}

Row {
    Icon(Icons.Default.Star, contentDescription = null)
    Text("Favorites")
}

Box {
    Image(painterResource(R.drawable.cover), contentDescription = null)
    Text("New", Modifier.align(Alignment.TopEnd))
}
  • Column lays children top to bottom. Its main axis is vertical and its cross axis is horizontal.
  • Row lays children left to right (right to left in right-to-left languages). Main axis horizontal, cross axis vertical.
  • Box stacks children in the order written, later ones on top. Each child is placed independently, so you use it for overlays, badges and backgrounds.

By default each of these wraps its content: a Row is as wide as its children, unless you ask for more with a modifier such as Modifier.fillMaxWidth().

Arrangement and Alignment

Two parameters decide where children go:

  • Arrangement distributes children along the main axis. For a Row it is horizontalArrangement; for a Column it is verticalArrangement.
  • Alignment positions children on the cross axis. For a Row it is verticalAlignment (Alignment.Top, CenterVertically, Bottom); for a Column it is horizontalAlignment (Start, CenterHorizontally, End).
Kotlin
// read-only example: needs Android and Compose
Row(
    modifier = Modifier.fillMaxWidth(),
    horizontalArrangement = Arrangement.SpaceBetween,
    verticalAlignment = Alignment.CenterVertically,
) {
    Text("Total")
    Text("$42.00")
}

The arrangement options only matter when there is free space (the container is larger than the sum of the children):

Arrangement Effect
Start / Top Children packed at the start
End / Bottom Children packed at the end
Center Children packed in the middle
SpaceBetween Equal gaps between children, none at the edges
SpaceAround Equal gaps between children, half a gap at each edge
SpaceEvenly The same gap between children and at both edges
spacedBy(8.dp) A fixed gap between children, packed at the start

Arrangement.spacedBy is the one you will use most inside lists and forms: it replaces many small margins. A Spacer(Modifier.width(8.dp)) or Modifier.height(16.dp) is the other tool for adding explicit empty space.

The stand-in below computes the position of three 40-unit-wide items inside a 300-unit container for each arrangement and draws a ruler where each character is 10 units. Compare the rows.

Kotlin Arrangements on the main axis (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

SpaceBetween leaves the edges empty and puts 90 units between items; SpaceEvenly uses 45 everywhere, edges included; SpaceAround gives 60 between and 30 at each edge. Cross-axis alignment is simpler: each child is shifted by 0, half or all of the free cross-axis space.

Weight: sharing the remaining space

Sometimes you want a child to take whatever is left. Inside a Row or Column, Modifier.weight(w) does that. Compose first measures all children without a weight, subtracts their sizes from the container, and then divides the remainder between weighted children in proportion to their weights.

Kotlin
// read-only example: needs Android and Compose
Row(Modifier.fillMaxWidth()) {
    Icon(Icons.Default.Person, contentDescription = null)         // fixed size
    Text("A long name that may need space", Modifier.weight(1f))   // takes the rest
    Text("12:30")                                                   // fixed size
}

With weight(1f) and weight(2f) in the same Row, the second child gets twice as much of the remaining space as the first. By default weight also forces the child to that exact size (fill = true); pass fill = false to let it be smaller. weight is only available inside RowScope and ColumnScope, so it is not a general modifier.

The calculator below mirrors the rule: fixed children first, then the weights split what is left. The third case shows what happens when the fixed children already use all the width.

Kotlin Row weight calculator (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

In the last case the fixed children total 130, more than the 100 available, so the weighted child gets 0. A weighted child never gets negative space. In the real system the fixed children themselves would be clipped by the parent's constraints, which leads to the next topic.

Constraints go down, sizes go up

Compose measures each layout node once, in a single pass, which is a big reason it is fast. The protocol is:

  1. A parent gives each child constraints: a minimum and maximum width and height.
  2. The child measures itself (and its own children) inside those constraints and reports a size.
  3. The parent decides where to place each child.
flowchart TD
    P["Parent<br/>receives constraints from its own parent"] -->|"constraints: min and max width and height"| C["Child<br/>chooses a size inside them"]
    C -->|"size: width and height"| P
    P --> PL["Parent places the child<br/>at an x and y position"]

Constraints flow down, sizes flow up, and the parent then places each child.

A child can never pick a size outside its constraints. If a parent allows widths between 0 and 200 and a child wants 500, it gets 200. This explains many surprises, such as a Modifier.size(500.dp) inside a smaller parent not being 500 dp wide. It also explains why a Row with a fillMaxWidth() child inside a horizontally scrolling parent misbehaves: a scrolling container passes unbounded maximum width, and "fill the maximum" has no meaning there.

Box follows the same rules and adds one more: each child can align itself, and Modifier.matchParentSize() makes a child the size of the box without influencing it, which is how you draw a background behind content that decides the size.

ConstraintLayout at a glance

For layouts that would need deep nesting, there is ConstraintLayout from the separate artifact androidx.constraintlayout:constraintlayout-compose. Children are linked to each other or to the parent by references:

Kotlin
// read-only example: needs Android, Compose and the constraintlayout-compose dependency
ConstraintLayout(Modifier.fillMaxWidth()) {
    val (avatar, name) = createRefs()
    Image(
        painter = painterResource(R.drawable.avatar),
        contentDescription = null,
        modifier = Modifier.constrainAs(avatar) {
            start.linkTo(parent.start)
            top.linkTo(parent.top)
        },
    )
    Text(
        "Ada Lovelace",
        modifier = Modifier.constrainAs(name) {
            start.linkTo(avatar.end, margin = 12.dp)
            top.linkTo(avatar.top)
        },
    )
}

Reach for it when elements must be aligned across rows or sized relative to one another (guidelines, barriers, chains). For ordinary screens nested Row, Column and Box are simpler and just as fast, because Compose handles deep nesting cheaply, unlike the old View system.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a Row, which parameter controls how children are spread along the horizontal direction?

    Arrangement works on the main axis (horizontal for a Row). Alignment works on the cross axis, which is vertical for a Row, so the parameter is verticalAlignment.
  2. 2. A 300-wide Row holds three 40-wide children with Arrangement.SpaceEvenly. What is the gap before the first child?

    Free space is 300 - 120 = 180. SpaceEvenly divides it into n + 1 = 4 equal gaps, including both edges, so each gap (and the offset of the first child) is 45.
  3. 3. How does Modifier.weight distribute space in a Row?

    Children without weight are measured first. What is left is split by the weights, so weight(2f) gets twice as much as weight(1f). Weighted children never get negative space.
  4. 4. What happens if a child asks for a size larger than its constraints allow?

    A child must choose a size within the constraints its parent gave it, so a request that is too large is capped at the maximum.
  5. 5. Which layout puts children on top of each other?

    Box stacks its children in the order written. Column stacks vertically, Row horizontally, and Spacer only adds empty space.

Summary

  • Column stacks vertically, Row horizontally, Box on top of each other; nest them to build screens.
  • Arrangement spreads children along the main axis (only visible when there is free space); Alignment positions them on the cross axis.
  • Arrangement.spacedBy and Spacer add explicit gaps.
  • Modifier.weight splits the space left over after unweighted children are measured.
  • Constraints go down, sizes go up, and a child can never exceed its constraints; layouts are measured once per pass.
  • ConstraintLayout helps with complex relative layouts; most screens do not need it.
  • The Compose code is read-only; the TryIt blocks are stand-ins that run the same arithmetic.

Next: Modifiers