Jetpack Compose의 Box: 개념, composable 속성 및 작동 방식

Jetpack Compose의 Box란?

Box는 자식 요소를 동일한 영역에 배치하고 서로 위에 쌓는 composable 함수입니다. 첫 번째 자식 요소는 맨 아래에, 마지막 요소는 맨 위에 그려집니다. 기본적으로 Box는 가장 큰 자식 요소의 크기에 맞게 조정됩니다.

Row 및 Column과 달리 Box는 요소를 순차적으로 정렬하지 않습니다. 모든 자식 요소는 동일한 영역을 차지하고 서로 겹칠 수 있습니다. 이로 인해 Box는 인터페이스 레이어를 구성하는 데 필수적입니다.

Box의 크기는 다음 규칙에 따라 결정됩니다. 자식 요소에 고정 크기가 없으면 Box는 최소 크기로 축소됩니다. 하나 이상의 자식 요소에 Modifier.fillMaxSize가 있으면 Box는 최대까지 확장됩니다.

Android Developers Blog, 2024에 따르면 Box는 요소가 순차적 배열을 필요로 하지 않는 경우 Compose에서 가장 효율적인 컨테이너입니다. Box는 Row 및 Column과 달리 위치 지정을 위한 추가 측정을 수행하지 않습니다.

Box 기본 시그니처

Box는 modifier, contentAlignment 및 propagateMinConstraints 매개변수를 허용합니다. 모든 자식 요소는 content 블록에 전달되며, 각각 고유한 수정자를 가질 수 있습니다.

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

Box의 ContentAlignment 및 Modifier.align

contentAlignment는 모든 자식 요소의 기본 정렬을 설정하는 Box 매개변수입니다. 지정하지 않으면 Alignment.TopStart가 사용되어 요소가 컨테이너의 왼쪽 상단 모서리에 배치됩니다.

Modifier.align을 사용하면 contentAlignment와 관계없이 특정 자식 요소의 정렬을 재정의할 수 있습니다. 예를 들어 Alignment.Center가 있는 Box는 Modifier.align(Alignment.BottomEnd)가 있는 요소를 포함할 수 있으며 오른쪽 아래 모서리에 고정됩니다.

Material Design Guidelines, 2025에 따르면 Modifier.align은 배경 이미지 위에 배지와 아이콘을 배치하는 데 유용합니다. 이를 통해 Box의 모든 콘텐츠에 일반 정렬을 설정하고 개별 요소에 대해 재정의할 수 있습니다.

Alignment 값 표

Modifier.align 예제

이 예제에서 Box는 배경 이미지와 오른쪽 아래 모서리의 배지를 포함합니다. Modifier.align(BottomEnd)는 Box의 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)
        )
    }
}

zIndex를 사용한 레이어 관리

Modifier.zIndex는 Box 내부 요소의 그리기 순서를 제어합니다. 기본적으로 요소는 선언 순서대로 그려집니다. 첫 번째 요소는 맨 아래, 마지막 요소는 맨 위입니다. zIndex는 이 순서를 재정의합니다.

zIndex 2.0f가 있는 요소는 코드에서의 순서와 관계없이 zIndex 1.0f가 있는 요소 위에 그려집니다. 음수 zIndex 값은 요소를 다른 요소 아래에 배치합니다. Android Developers, 2024에 따르면 zIndex는 그리기 순서에만 영향을 미치며 터치 이벤트 처리에는 영향을 주지 않습니다.

zIndex는 애니메이션 및 드래그 가능한 구성 요소에서 특히 유용하며, 요소가 일시적으로 다른 요소 위로 올라가야 하는 경우에 사용됩니다. 예를 들어 카드를 드래그할 때 zIndex가 증가하여 인접 요소에 의해 가려지지 않습니다.

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

Box 사용 실제 예제

Box는 이미지에 텍스트를 오버레이하는 데 널리 사용됩니다. 배경 이미지가 먼저 배치된 다음 배경 위에 위치하도록 Modifier.align과 함께 텍스트가 배치됩니다.

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

두 번째 예제는 로딩 표시기를 만들기 위한 Box입니다. Box가 전체 화면 영역을 차지하고 CircularProgressIndicator가 contentAlignment를 통해 중앙에 배치됩니다.

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

Box 크기 제약 조건

Box는 기본적으로 콘텐츠 크기에 맞게 조정됩니다. 자식 요소의 크기가 다른 경우 Box는 가장 큰 요소의 크기를 사용합니다. 자식 요소가 없으면 Box는 최소 크기로 축소됩니다.

Modifier.clipToBounds는 자식 요소의 렌더링을 Box 경계로 제한합니다. 이 수정자가 없으면 자식 요소가 Box 밖으로 확장될 수 있습니다. Material Design Guidelines, 2025에 따르면 Box 내에서 Modifier.scale 또는 Modifier.graphicsLayer를 사용할 때 clipToBounds는 필수입니다.

propagateMinConstraints는 최소 크기 제약 조건을 자식 요소에 전파하는 Box 매개변수입니다. true로 설정하면 자식 요소가 Modifier.size 또는 Modifier.constrain을 통해 Box에 설정된 최소 크기보다 작아질 수 없습니다.

• Box — 크기가 설정되지 않고 fillMaxSize가 있는 자식 요소가 없는 경우 최소 컨테이너
• Modifier.clipToBounds 콘텐츠가 Box 경계 밖으로 나가는 것을 방지
• propagateMinConstraints 최소 제약 조건을 자식 요소에 전파