Box en Jetpack Compose: qué es, propiedades composables y cómo funciona

¿Qué es Box en Jetpack Compose?

Box es una función composable que coloca elementos secundarios en la misma área, apilándolos unos sobre otros. El primer elemento secundario se dibuja abajo, el último arriba. Por defecto, Box se ajusta al tamaño del elemento secundario más grande.

A diferencia de Row y Column, Box no organiza elementos secuencialmente — todos los elementos secundarios ocupan la misma área y pueden superponerse. Esto hace que Box sea indispensable para componer capas de interfaz.

El tamaño de Box se determina por la regla: si ningún elemento secundario tiene un tamaño fijo, Box se colapsa al tamaño mínimo. Si al menos un elemento secundario tiene Modifier.fillMaxSize, Box se expande al máximo.

Según el Android Developers Blog, 2024, Box es el contenedor más eficiente en Compose para casos donde los elementos no requieren disposición secuencial. Box no realiza mediciones adicionales para el posicionamiento, a diferencia de Row y Column.

Firma básica de Box

Box acepta los parámetros modifier, contentAlignment y propagateMinConstraints. Todos los elementos secundarios se pasan en el bloque content, donde cada uno puede tener sus propios modificadores.

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

ContentAlignment y Modifier.align en Box

contentAlignment es un parámetro de Box que establece la alineación predeterminada para todos los elementos secundarios. Si no se especifica, se utiliza Alignment.TopStart — los elementos se colocan en la esquina superior izquierda del contenedor.

Modifier.align permite anular la alineación de un elemento secundario específico independientemente de contentAlignment. Por ejemplo, un Box con Alignment.Center puede contener un elemento con Modifier.align(Alignment.BottomEnd) que se fijará en la esquina inferior derecha.

Según las Material Design Guidelines, 2025, Modifier.align es útil para posicionar insignias e iconos sobre imágenes de fondo. Esto permite establecer una alineación general para todo el contenido de Box y anularla para elementos individuales.

Tabla de valores de Alignment

Ejemplo con Modifier.align

En este ejemplo, Box contiene una imagen de fondo y una insignia en la esquina inferior derecha. Modifier.align(BottomEnd) posiciona la insignia independientemente del contentAlignment de Box.

@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)
        )
    }
}

Gestión de capas con zIndex

Modifier.zIndex controla el orden de dibujo de los elementos dentro de Box. Por defecto, los elementos se dibujan en el orden de declaración — el primer elemento abajo, el último arriba. zIndex anula este orden.

Un elemento con zIndex 2.0f se dibuja sobre un elemento con zIndex 1.0f, independientemente de su orden en el código. Los valores negativos de zIndex colocan un elemento debajo de los demás. Según Android Developers, 2024, zIndex solo afecta al orden de dibujo, no al manejo de eventos táctiles.

zIndex es especialmente útil en animaciones y componentes arrastrables, donde un elemento debe elevarse temporalmente sobre los demás. Por ejemplo, al arrastrar una tarjeta, su zIndex aumenta para que no sea superpuesta por elementos vecinos.

@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))
    }
}

Ejemplos prácticos de uso de Box

Box se usa ampliamente para superponer texto sobre imágenes. La imagen de fondo se coloca primero, luego el texto con Modifier.align para posicionarlo sobre el fondo.

@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 = "Título",
            color = Color.White,
            modifier = Modifier.align(Alignment.BottomStart)
                .padding(16.dp)
        )
    }
}

El segundo ejemplo es Box para crear un indicador de carga. Box ocupa toda el área de la pantalla, y CircularProgressIndicator se centra mediante contentAlignment.

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

Restricciones de tamaño de Box

Box por defecto se ajusta al tamaño de su contenido. Si los elementos secundarios tienen diferentes tamaños, Box toma el tamaño del elemento más grande. Cuando no hay elementos secundarios, Box se colapsa al tamaño mínimo.

Modifier.clipToBounds restringe el renderizado de elementos secundarios a los límites de Box. Sin este modificador, los elementos secundarios pueden extenderse más allá de Box. Según las Material Design Guidelines, 2025, clipToBounds es obligatorio al usar Modifier.scale o Modifier.graphicsLayer dentro de Box.

propagateMinConstraints es un parámetro de Box que pasa las restricciones de tamaño mínimo a los elementos secundarios. Si se establece en true, los elementos secundarios no pueden ser más pequeños que el tamaño mínimo de Box. Este comportamiento es importante al crear contenedores personalizados con tamaños mínimos fijos.

• Box — contenedor mínimo si no se establecen tamaños y ningún elemento secundario tiene fillMaxSize
• Modifier.clipToBounds evita que el contenido se salga de los límites de Box
• propagateMinConstraints pasa restricciones mínimas a los elementos secundarios