Box no Jetpack Compose: o que é, propriedades composable e como funciona

O que é Box no Jetpack Compose?

Box é uma função composable que coloca elementos filhos na mesma área, empilhando-os uns sobre os outros. O primeiro elemento filho é desenhado embaixo, o último em cima. Por padrão, o Box se ajusta ao tamanho do maior elemento filho.

Diferente de Row e Column, o Box não organiza elementos sequencialmente — todos os elementos filhos ocupam a mesma área e podem se sobrepor. Isso torna o Box indispensável para compor camadas de interface.

O tamanho do Box é determinado pela regra: se nenhum elemento filho tiver tamanho fixo, o Box colapsa para o tamanho mínimo. Se pelo menos um elemento filho tiver Modifier.fillMaxSize, o Box se expande ao máximo.

De acordo com o Android Developers Blog, 2024, o Box é o contêiner mais eficiente no Compose para casos onde os elementos não exigem disposição sequencial. O Box não realiza medições adicionais para posicionamento, ao contrário de Row e Column.

Assinatura básica do Box

Box aceita os parâmetros modifier, contentAlignment e propagateMinConstraints. Todos os elementos filhos são passados no bloco content, onde cada um pode ter seus próprios modificadores.

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

ContentAlignment e Modifier.align no Box

contentAlignment é um parâmetro do Box que define o alinhamento padrão para todos os elementos filhos. Se não for especificado, Alignment.TopStart é usado — os elementos são colocados no canto superior esquerdo do contêiner.

Modifier.align permite sobrescrever o alinhamento de um elemento filho específico independentemente do contentAlignment. Por exemplo, um Box com Alignment.Center pode conter um elemento com Modifier.align(Alignment.BottomEnd) que será fixado no canto inferior direito.

De acordo com as Material Design Guidelines, 2025, Modifier.align é útil para posicionar badges e ícones sobre imagens de fundo. Isso permite definir um alinhamento geral para todo o conteúdo do Box e sobrescrevê-lo para elementos individuais.

Tabela de valores de Alignment

Exemplo com Modifier.align

Neste exemplo, Box contém uma imagem de fundo e um badge no canto inferior direito. Modifier.align(BottomEnd) posiciona o badge independentemente do contentAlignment do 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)
        )
    }
}

Gerenciamento de camadas com zIndex

Modifier.zIndex controla a ordem de desenho dos elementos dentro do Box. Por padrão, os elementos são desenhados na ordem de declaração — o primeiro elemento embaixo, o último em cima. zIndex sobrescreve essa ordem.

Um elemento com zIndex 2.0f é desenhado acima de um elemento com zIndex 1.0f, independentemente de sua ordem no código. Valores negativos de zIndex colocam um elemento abaixo dos demais. De acordo com Android Developers, 2024, zIndex afeta apenas a ordem de desenho, não o tratamento de eventos de toque.

zIndex é especialmente útil em animações e componentes arrastáveis, onde um elemento precisa se elevar temporariamente sobre os outros. Por exemplo, ao arrastar um cartão, seu zIndex aumenta para não ser sobreposto por elementos vizinhos.

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

Exemplos práticos de uso do Box

Box é amplamente usado para sobrepor texto em imagens. A imagem de fundo é colocada primeiro, depois o texto com Modifier.align para posicionamento sobre o fundo.

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

O segundo exemplo é Box para criar um indicador de carregamento. Box ocupa toda a área da tela, e CircularProgressIndicator é centralizado via contentAlignment.

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

Restrições de tamanho do Box

Box por padrão se ajusta ao tamanho do seu conteúdo. Se os elementos filhos tiverem tamanhos diferentes, o Box assume o tamanho do maior elemento. Quando não há elementos filhos, o Box colapsa para o tamanho mínimo.

Modifier.clipToBounds restringe a renderização de elementos filhos aos limites do Box. Sem este modificador, os elementos filhos podem se estender além do Box. De acordo com as Material Design Guidelines, 2025, clipToBounds é obrigatório ao usar Modifier.scale ou Modifier.graphicsLayer dentro do Box.

propagateMinConstraints é um parâmetro do Box que passa restrições de tamanho mínimo para os elementos filhos. Se definido como true, os elementos filhos não podem ser menores que o tamanho mínimo definido para o Box via Modifier.size ou Modifier.constrain.

• Box — contêiner mínimo se nenhum tamanho for definido e nenhum elemento filho tiver fillMaxSize
• Modifier.clipToBounds evita que o conteúdo vaze para fora dos limites do Box
• propagateMinConstraints passa restrições mínimas para os elementos filhos