Google is committed to advancing racial equity for Black communities. See how.

ColumnScope

@Immutable interface ColumnScope
androidx.compose.foundation.layout.ColumnScope

Scope for the children of Column.

Summary

Nested classes
companion

Public methods
open Modifier

Align the element horizontally within the Column.

open Modifier

Position the element horizontally such that its alignmentLine aligns with sibling elements also configured to alignWithSiblings.

open Modifier
Modifier.alignWithSiblings(alignmentLineBlock: (Measured) -> Int)

Position the element horizontally such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignWithSiblings.

open Modifier

open Modifier
Modifier.weight(@FloatRange(0.0, 3.4E38, false) weight: Float, fill: Boolean = true)

Size the element's height proportional to its weight relative to other weighted sibling elements in the Column.

Extension functions
From androidx.compose.animation
Unit
ColumnScope.AnimatedVisibility(visible: Boolean, modifier: Modifier = Modifier, enter: EnterTransition = fadeIn() + expandVertically(), exit: ExitTransition = fadeOut() + shrinkVertically(), initiallyVisible: Boolean = visible, content: () -> Unit)

AnimatedVisibility composable animates the appearance and disappearance of its content, as visible value changes.

Public methods

align

@Stable open fun Modifier.align(alignment: Alignment.Horizontal): Modifier

Align the element horizontally within the Column. This alignment will have priority over the Column's horizontalAlignment parameter.

Example usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.preferredSize

Column(Modifier.fillMaxWidth()) {
    // The child with no align modifier is positioned by default so that its start edge
    // aligned with the start edge of the horizontal axis.

    Box(Modifier.preferredSize(80.dp, 40.dp).background(Color.Magenta))
    // Alignment.Start, the child will be positioned so that its start edge is aligned with
    // the start edge of the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .align(Alignment.Start)
            .background(Color.Red)
    )
    // Alignment.Center, the child will be positioned so that its center is in the middle of
    // the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .align(Alignment.CenterHorizontally)
            .background(Color.Yellow)
    )
    // Alignment.End, the child will be positioned so that its end edge aligned to the end of
    // the horizontal axis.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .align(Alignment.End)
            .background(Color.Green)
    )
}

alignWithSiblings

@Stable open fun Modifier.alignWithSiblings(alignmentLine: VerticalAlignmentLine): Modifier

Position the element horizontally such that its alignmentLine aligns with sibling elements also configured to alignWithSiblings. alignWithSiblings is a form of align, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignWithSiblings will align horizontally using the specified VerticalAlignmentLines or values provided using the other alignWithSiblings overload, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Start align in Column, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Column has the alignWithSiblings modifier specified the element will be positioned as if it had Alignment.Start align.

Example usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.preferredSize
import androidx.compose.ui.Layout
import androidx.compose.ui.VerticalAlignmentLine

// Alignment lines provided by the RectangleWithStartEnd layout. We need to create these
// local alignment lines because Compose is currently not providing any top-level out of
// the box vertical alignment lines. Two horizontal alignment lines are provided though:
// FirstBaseline and LastBaseline, but these can only be used to align vertically children
// of Row because the baselines are horizontal. Therefore, we create these vertical alignment
// lines, that refer to the start and end of the RectangleWithStartEnd layout which knows
// how to provide them. Then Column will know how to align horizontally children such
// that the positions of the alignment lines coincide, as asked by alignWithSiblings.
val start = VerticalAlignmentLine(::min)
val end = VerticalAlignmentLine(::min)

@Composable
fun RectangleWithStartEnd(modifier: Modifier = Modifier, color: Color, width: Dp, height: Dp) {
    Layout(
        children = { },
        modifier = modifier.background(color = color)
    ) { _, constraints ->
        val widthPx = max(width.toIntPx(), constraints.minWidth)
        val heightPx = max(height.toIntPx(), constraints.minHeight)
        layout(widthPx, heightPx, mapOf(start to 0, end to widthPx)) {}
    }
}

Column {
    // Center of the first rectangle is aligned to the right edge of the second rectangle and
    // left edge of the third one.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .alignWithSiblings { it.width / 2 }
            .background(Color.Blue)
    )
    RectangleWithStartEnd(
        Modifier.alignWithSiblings(end),
        color = Color.Magenta,
        width = 80.dp,
        height = 40.dp
    )
    RectangleWithStartEnd(
        Modifier.alignWithSiblings(start),
        color = Color.Red,
        width = 80.dp,
        height = 40.dp
    )
}

alignWithSiblings

@Stable open fun Modifier.alignWithSiblings(alignmentLineBlock: (Measured) -> Int): Modifier

Position the element horizontally such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignWithSiblings. alignWithSiblings is a form of align, so both modifiers will not work together if specified for the same layout. Within a Column, all components with alignWithSiblings will align horizontally using the specified VerticalAlignmentLines or values obtained from alignmentLineBlock, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Start align in Column, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Column has the alignWithSiblings modifier specified the element will be positioned as if it had Alignment.Start align.

Example usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.preferredSize

Column {
    // Center of the first rectangle is aligned to the right edge of the second rectangle and
    // left edge of the third one.
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .alignWithSiblings { it.width / 2 }
            .background(Color.Blue)
    )
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .alignWithSiblings { it.width }
            .background(Color.Magenta)
    )
    Box(
        Modifier.preferredSize(80.dp, 40.dp)
            .alignWithSiblings { 0 }
            .background(Color.Red)
    )
}

gravity

@Stable open fun Modifier.gravity(align: Alignment.Horizontal): Modifier

Deprecated.

weight

@Stable open fun Modifier.weight(
    @FloatRange(0.0, 3.4E38, false) weight: Float,
    fill: Boolean = true
): Modifier

Size the element's height proportional to its weight relative to other weighted sibling elements in the Column. The parent will divide the vertical space remaining after measuring unweighted child elements and distribute it according to this weight. When fill is true, the element will be forced to occupy the whole height allocated to it. Otherwise, the element is allowed to be smaller - this will result in Column being smaller, as the unused allocated height will not be redistributed to other siblings.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.preferredSize
import androidx.compose.foundation.layout.preferredWidth

Column {
    // The child with no weight will have the specified size.
    Box(Modifier.preferredSize(40.dp, 80.dp).background(Color.Magenta))
    // Has weight, the child will occupy half of the remaining height.
    Box(Modifier.preferredWidth(40.dp).weight(1f).background(Color.Yellow))
    // Has weight and does not fill, the child will occupy at most half of the remaining height.
    // Therefore it will occupy 80.dp (its preferred height) if the assigned height is larger.
    Box(
        Modifier.preferredSize(40.dp, 80.dp)
            .weight(1f, fill = false)
            .background(Color.Green)
    )
}