Box in Jetpack Compose: cos'è, proprietà composable e come funziona

Cos'è Box in Jetpack Compose?

Box è una funzione composable che posiziona gli elementi figli nella stessa area, impilandoli uno sopra l'altro. Il primo elemento figlio viene disegnato in basso, l'ultimo in alto. Per impostazione predefinita, Box si adatta alla dimensione dell'elemento figlio più grande.

A differenza di Row e Column, Box non dispone gli elementi in sequenza — tutti gli elementi figli occupano la stessa area e possono sovrapporsi. Questo rende Box indispensabile per comporre layer di interfaccia.

La dimensione di Box è determinata dalla regola: se nessun elemento figlio ha una dimensione fissa, Box si riduce alla dimensione minima. Se almeno un elemento figlio ha Modifier.fillMaxSize, Box si espande al massimo.

Secondo Android Developers Blog, 2024, Box è il contenitore più efficiente in Compose per i casi in cui gli elementi non richiedono una disposizione sequenziale. Box non esegue misurazioni aggiuntive per il posizionamento, a differenza di Row e Column.

Firma di base di Box

Box accetta i parametri modifier, contentAlignment e propagateMinConstraints. Tutti gli elementi figli vengono passati nel blocco content, dove ciascuno può avere i propri modificatori.

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

ContentAlignment e Modifier.align in Box

contentAlignment è un parametro di Box che imposta l'allineamento predefinito per tutti gli elementi figli. Se non specificato, viene utilizzato Alignment.TopStart — gli elementi vengono posizionati nell'angolo superiore sinistro del contenitore.

Modifier.align consente di sovrascrivere l'allineamento per un elemento figlio specifico indipendentemente da contentAlignment. Ad esempio, un Box con Alignment.Center può contenere un elemento con Modifier.align(Alignment.BottomEnd) che verrà fissato nell'angolo inferiore destro.

Secondo le Material Design Guidelines, 2025, Modifier.align è utile per posizionare badge e icone su immagini di sfondo. Ciò consente di impostare un allineamento generale per tutto il contenuto di Box e sovrascriverlo per elementi individuali.

Tabella dei valori di Alignment

Esempio con Modifier.align

In questo esempio, Box contiene un'immagine di sfondo e un badge nell'angolo inferiore destro. Modifier.align(BottomEnd) posiziona il badge indipendentemente dal contentAlignment di 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)
        )
    }
}

Gestione dei layer con zIndex

Modifier.zIndex controlla l'ordine di disegno degli elementi all'interno di Box. Per impostazione predefinita, gli elementi vengono disegnati nell'ordine di dichiarazione — il primo elemento in basso, l'ultimo in alto. zIndex sovrascrive questo ordine.

Un elemento con zIndex 2.0f viene disegnato sopra un elemento con zIndex 1.0f, indipendentemente dal loro ordine nel codice. I valori negativi di zIndex posizionano un elemento sotto gli altri. Secondo Android Developers, 2024, zIndex influisce solo sull'ordine di disegno, non sulla gestione degli eventi touch.

zIndex è particolarmente utile nelle animazioni e nei componenti trascinabili, dove un elemento deve sollevarsi temporaneamente sopra gli altri. Ad esempio, quando si trascina una carta, il suo zIndex aumenta per non essere coperta dagli elementi vicini.

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

Esempi pratici di utilizzo di Box

Box è ampiamente utilizzato per sovrapporre testo su immagini. L'immagine di sfondo viene posizionata per prima, poi il testo con Modifier.align per posizionarlo sopra lo sfondo.

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

Il secondo esempio è Box per creare un indicatore di caricamento. Box occupa l'intera area dello schermo e CircularProgressIndicator viene centrato tramite contentAlignment.

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

Vincoli di dimensione di Box

Box per impostazione predefinita si adatta alla dimensione del suo contenuto. Se gli elementi figli hanno dimensioni diverse, Box assume la dimensione dell'elemento più grande. Quando non ci sono elementi figli, Box si riduce alla dimensione minima.

Modifier.clipToBounds limita il rendering degli elementi figli ai confini di Box. Senza questo modificatore, gli elementi figli possono estendersi oltre Box. Secondo le Material Design Guidelines, 2025, clipToBounds è obbligatorio quando si utilizza Modifier.scale o Modifier.graphicsLayer all'interno di Box.

propagateMinConstraints è un parametro di Box che trasmette i vincoli di dimensione minima agli elementi figli. Se impostato su true, gli elementi figli non possono essere più piccoli della dimensione minima impostata per Box tramite Modifier.size o Modifier.constrain.

• Box — contenitore minimo se nessuna dimensione è impostata e nessun elemento figlio ha fillMaxSize
• Modifier.clipToBounds impedisce al contenuto di fuoriuscire dai confini di Box
• propagateMinConstraints trasmette i vincoli minimi agli elementi figli