Box in Jetpack Compose: what it is, composable properties and how it works

What is Box in Jetpack Compose

Box is a composable function that places child elements in the same area, stacking them on top of each other. The first child element is drawn at the bottom, the last at the top. By default, Box adjusts to the size of the largest child element.

Unlike Row and Column, Box does not arrange elements sequentially — all child elements occupy the same area and can overlap each other. This makes Box indispensable for composing interface layers.

The size of Box is determined by the rule: if no child element has a fixed size, Box collapses to the minimum size. If at least one child element has Modifier.fillMaxSize, Box expands to the maximum.

According to the Android Developers Blog, 2024, Box is the most efficient container in Compose for cases where elements do not require sequential arrangement. Box does not perform additional measurements for positioning, unlike Row and Column.

Basic Box Signature

Box accepts the modifier, contentAlignment, and propagateMinConstraints parameters. All child elements are passed in the content block, where each can have its own modifiers.

@Composable
fun BoxExample() {
    Box(
        modifier = Modifier.size(200.dp),
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier.fillMaxSize().background(Color.Blue)
        )
        Text(
            text = "Hello",
            color = Color.White
        )
    }
}

ContentAlignment and Modifier.align in Box

contentAlignment is a Box parameter that sets the default alignment for all child elements. If not specified, Alignment.TopStart is used — elements are placed in the top-left corner of the container.

Modifier.align allows you to override the alignment for a specific child element independently of contentAlignment. For example, a Box with Alignment.Center can contain an element with Modifier.align(Alignment.BottomEnd) that will be pinned to the bottom-right corner.

According to the Material Design Guidelines, 2025, Modifier.align is useful for positioning badges and icons over background images. This allows you to set a general alignment for all Box content and override it for individual elements.

Alignment Values Table

Example with Modifier.align

In this example, Box contains a background image and a badge in the bottom-right corner. Modifier.align(BottomEnd) positions the badge independently of the Box's contentAlignment.

@Composable
fun BadgeExample() {
    Box(
        modifier = Modifier.size(120.dp),
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier.size(100.dp).background(Color.Gray)
        )
        Box(
            modifier = Modifier
                .size(30.dp)
                .align(Alignment.BottomEnd)
                .background(Color.Red, CircleShape)
        )
    }
}

Layer Management with zIndex

Modifier.zIndex controls the drawing order of elements inside Box. By default, elements are drawn in declaration order — the first element at the bottom, the last at the top. zIndex overrides this order.

An element with zIndex 2.0f is drawn above an element with zIndex 1.0f, regardless of their order in code. Negative zIndex values push an element below others. According to Android Developers, 2024, zIndex only affects drawing order but not touch event handling.

zIndex is especially useful in animations and draggable components, where an element needs to temporarily rise above others. For example, when dragging a card, its zIndex increases so it is not overlapped by neighboring elements.

@Composable
fun ZIndexExample() {
    Box(modifier = Modifier.size(150.dp)) {
        Box(modifier = Modifier.size(80.dp)
            .align(Alignment.TopStart)
            .zIndex(2.0f)
            .background(Color.Green))
        Box(modifier = Modifier.size(100.dp)
            .align(Alignment.Center)
            .zIndex(1.0f)
            .background(Color.Blue))
    }
}

Practical Examples of Using Box

Box is widely used for overlaying text on images. The background image is placed first, then text with Modifier.align for positioning over the background.

@Composable
fun ImageWithOverlay() {
    Box(modifier = Modifier.fillMaxWidth().height(200.dp)) {
        Image(
            painter = painterResource(R.drawable.photo),
            contentDescription = "Photo",
            modifier = Modifier.fillMaxSize(),
            contentScale = ContentScale.Crop
        )
        Box(
            modifier = Modifier.fillMaxSize()
                .background(Color.Black.copy(alpha = 0.4f))
        )
        Text(
            text = "Title",
            color = Color.White,
            modifier = Modifier.align(Alignment.BottomStart)
                .padding(16.dp)
        )
    }
}

The second example is Box for creating a loading indicator. Box occupies the entire screen area, and CircularProgressIndicator is centered via contentAlignment.

@Composable
fun LoadingOverlay() {
    Box(
        modifier = Modifier.fillMaxSize(),
        contentAlignment = Alignment.Center
    ) {
        CircularProgressIndicator(
            modifier = Modifier.size(48.dp)
        )
    }
}

Box Size Constraints

Box by default adjusts to the size of its content. If child elements have different sizes, Box takes the size of the largest element. When there are no child elements, Box collapses to the minimum size.

Modifier.clipToBounds restricts child element rendering to the Box boundaries. Without this modifier, child elements can extend beyond the Box. According to the Material Design Guidelines, 2025, clipToBounds is mandatory when using Modifier.scale or Modifier.graphicsLayer inside Box.

propagateMinConstraints is a Box parameter that passes minimum size constraints to child elements. If set to true, child elements cannot be smaller than the Box's minimum size. This behavior is important when creating custom containers with fixed minimum sizes.

• Box — minimal container if no sizes are set and no child elements have fillMaxSize
• Modifier.clipToBounds prevents content from spilling outside Box boundaries
• propagateMinConstraints passes minimum constraints to child elements