GridConfigurationScope

@LayoutScopeMarker
@ExperimentalGridApi
interface GridConfigurationScope : Density

Scope for configuring the structure of a Grid.

This interface is implemented by the configuration block in Grid. It allows defining columns, rows, and gaps.

The order in which column and row functions are called within the config block is important. Tracks are added to the grid definition sequentially based on these calls. For example, calling column(100.dp) twice defines two columns.

Gap configuration calls (gap, rowGap, columnGap) follow a "last-call-wins" policy for their respective axes.

Properties

val constraints: Constraints

The layout constraints passed to this Grid from its parent.

These constraints represent the minimum and maximum size limits that the parent has imposed on this Grid. This can be useful for creating responsive layouts that adapt based on available space.

var flow: GridFlow

The direction in which items that do not specify a position are placed. Defaults to GridFlow.Row.

@ExperimentalGridApi
val Int.fr: Fr

Creates an Fr unit from an Int.

@ExperimentalGridApi
val Float.fr: Fr

Creates an Fr unit from a Float.

@ExperimentalGridApi
val Double.fr: Fr

Creates an Fr unit from a Double.

Functions

fun column(size: Dp)

Defines a fixed-width column. Maps to GridTrackSize.Fixed.

fun column(weight: Fr)

Defines a flexible column. Maps to GridTrackSize.Flex.

fun column(@FloatRange(from = 0.0, to = 1.0) percentage: Float)

Defines a percentage-based column. Maps to GridTrackSize.Percentage.

Parameters

fun column(size: GridTrackSize)

Defines a new column track with the specified size.

fun row(size: Dp)

Defines a fixed-width row. Maps to GridTrackSize.Fixed.

fun row(weight: Fr)

Defines a flexible row. Maps to GridTrackSize.Flex.

fun row(@FloatRange(from = 0.0, to = 1.0) percentage: Float)

Defines a percentage-based row. Maps to GridTrackSize.Percentage.

Parameters

fun row(size: GridTrackSize)

Defines a new row track with the specified size.

fun gap(all: Dp)

Sets both the row and column gaps (gutters) to all.

Precedence: If this is called multiple times, or mixed with columnGap or rowGap, the last call takes precedence.

fun gap(row: Dp, column: Dp)

Sets independent gaps for rows and columns.

Precedence: If this is called multiple times, or mixed with columnGap or rowGap, the last call takes precedence.

fun columnGap(gap: Dp)

Sets the gap (gutter) size between columns.

Precedence: If this is called multiple times, the last call takes precedence. This call will overwrite the column component of any previous gap call.

fun rowGap(gap: Dp)

Sets the gap (gutter) size between rows.

Precedence: If this is called multiple times, the last call takes precedence. This call will overwrite the row component of any previous gap call.

fun minmax(min: Dp, max: Fr): GridTrackSize

A flexible track with an explicitly defined minimum base size and a flexible maximum size. Conceptually, this behaves identically to the CSS Grid minmax(min, max) function.

Usage with Lazy Lists: Because minmax relies on a predefined min size (e.g., 0.dp), it entirely bypasses the intrinsic measurement pass. This makes it the required choice when placing SubcomposeLayout-backed components (such as LazyColumn or LazyRow) inside a flexible grid track.

Parameters

Code Examples

GridConfigurationDslSample

@Composable
@OptIn(ExperimentalGridApi::class)
fun GridConfigurationDslSample() {
    Grid(
        config = {
            // This defines the first column
            column(100.dp)
            // This defines the second column
            column(1.fr)
            // This defines the first row
            row(50.dp)
            // The order is important. additional calls to row() or column() append tracks.
            gap(all = 8.dp) // Set both row and column gaps
            columnGap(16.dp) // Override column gap
        }
    ) {
        Box(
            modifier = Modifier.gridItem(row = 1, column = 1).background(Color.Blue).fillMaxSize(),
            contentAlignment = Alignment.Center,
        ) {
            Text("Row: 1, Column: 1", color = Color.White)
        }
        Box(
            modifier = Modifier.gridItem(row = 1, column = 1).background(Color.Blue).fillMaxSize(),
            contentAlignment = Alignment.Center,
        ) {
            Text("Row: 1, Column: 2", color = Color.White)
        }
    }
}

GridWithConstraints

@Composable
@OptIn(ExperimentalGridApi::class)
fun GridWithConstraints() {
    Grid(
        modifier = Modifier.fillMaxSize().padding(16.dp),
        config = {
            val maxWidthDp = constraints.maxWidth.toDp()
            if (maxWidthDp < 600.dp) {
                // Compact Layout: 2 Columns
                repeat(2) { column(1.fr) }
            } else {
                // Expanded Layout: 4 Columns
                repeat(4) { column(1.fr) }
            }
            // Rows are auto-generated based on content
            gap(8.dp)
        },
    ) {
        repeat(8) { index ->
            Box(
                modifier = Modifier.background(Color.Cyan).padding(24.dp),
                contentAlignment = Alignment.Center,
            ) {
                Text("Item $index")
            }
        }
    }
}